Skip to main content
The AI Adoption API tells you how far a company has adopted AI. For each company you get an overall level, a one-line explanation, its momentum, and a score for five areas: Add withEvidence=true to also get the evidence behind each area: the technologies, job ads, posts and people Firmable found.

Who can use it

Both kinds of API key work, with the same endpoint, responses and prices: Send the key as a bearer token, as with every Firmable endpoint:

Which company

Give one identifier for the company: Send exactly one. Sending both, or neither, returns 400.

Get one company

POST /ai-adoption with the company in the body:
Responses can carry other fields too. Ignore the ones you don’t use.
Levels are words, such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or ADVANCED. New levels can be added, so don’t fail on a level you don’t recognise.

Areas

Every area in company.dimensions has: Each area adds its own detail:

Get many at once

To get up to 100 companies in one call, put them in records. Add your own external_id to a row to match the answer back to your data. Each row takes company_id or domain, and rows can mix them.
results has one row per company, in the order you sent them. Each row has the same fields as a single answer. usage.billable_rows counts the rows you pay for.

When a company isn’t found

If Firmable has no AI adoption data for a company, or can’t match the domain, the answer still comes back with 200. company is null, error.code is not_found, and it’s free. In a batch, the other rows still come back.

Get the evidence

Add withEvidence=true to the URL to also get the evidence behind each area. It’s a query parameter, not part of the body.
Each answer then has an evidence object next to company, with one entry per area:
Items in each area also have: confidence_band is a band such as LOW, MEDIUM or HIGH. New values can be added, as with levels. An area with no evidence is left out of evidence. A company with no evidence at all has no evidence field. Check company.evidence_available to see what each area holds. withEvidence must be true or false; anything else returns 400.

Pricing

You pay only for companies Firmable has data for.
  • A batch is charged per row. A batch of 100 with 80 companies found counts 80.
  • Evidence is charged only when some comes back. With withEvidence=true, a company found with no evidence costs the same as one without evidence.
  • Part-credits carry over. Companies add up across requests, and a credit is taken each time your organisation reaches 5. Two companies today and three tomorrow cost 1 credit in total.
  • Each answer shows if it counts. usage.billable is true on an answer you pay for. A batch also returns usage.billable_rows.
  • You need enough credits up front. Before reading anything, Firmable checks your organisation could pay if every company were found: at least 1 credit for one company, 20 for a batch of 100, 3 for one company with evidence, or 300 for a batch of 100 with evidence. If not, the call returns 402 insufficient_credits and nothing is charged.

Errors

Errors return a status code and a JSON body:
See Get AI Adoption for every status and code.

Using an AI agent

The Firmable MCP server has a get_ai_adoption tool that returns the same data. See AI Adoption tool.