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:- Customer keys start with
fbl_. See Creating API keys. They spend your subscription credits first, then add-on credits. - Developer keys start with
fbl_dev_. See API keys and authentication. They spend developer credits.
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 incompany.dimensions has:
Each area adds its own detail:
Get many at once
To get up to 100 companies in one call, put them inrecords. 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 with200. company is null, error.code is not_found, and it’s free. In a batch, the
other rows still come back.
Get the evidence
AddwithEvidence=true to the URL to also get the evidence behind each area. It’s a query
parameter, not part of the body.
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.billableistrueon an answer you pay for. A batch also returnsusage.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_creditsand nothing is charged.
Errors
Errors return a status code and a JSON body:Using an AI agent
The Firmable MCP server has aget_ai_adoption tool that returns the same data. See
AI Adoption tool.