Skip to main content
POST

Description

Returns how far a company has adopted AI: an overall level, a one-line explanation, momentum, and a level for each of five areas (architecture, footprint, hiring, initiatives, workforce). Ask about one company, or up to 100 in a batch. See AI Adoption for the full guide.

Request body

Each company takes exactly one of company_id or domain. Any other field returns 400.

One company

A batch

A batch returns a results array with one answer per company, in the order sent, and usage.billable_rows.

Response

A single answer has input (what you sent), company (the AI adoption, or null when Firmable has none) and usage.billable. A company that isn’t found also has error.code set to not_found, and still returns 200. See AI Adoption for an example and every field.

Evidence

Add ?withEvidence=true to get an evidence object with each answer: one entry per area that has evidence, each with as_of, framework_version, item_count, truncated and items. The value must be true or false, and it can’t go in the body. See Get the evidence.

Credits

A batch is charged per row, and part-credits carry over between requests. usage.billable is true on each answer you pay for. Before reading anything, Firmable checks your organisation has enough credits to pay for every row as if each company were found. If not, the call returns 402 and nothing is charged. Customer keys spend subscription credits, then add-on credits. Developer keys spend developer credits.

Errors

Errors from this endpoint have this shape:
Failed requests are never charged.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

withEvidence
boolean
default:false

true adds an evidence object to each answer, at 3 credits per company with evidence. Must be true or false. Can't be sent in the body.

Body

application/json
company_id
string

A Firmable company ID. Send this or domain, not both.

Example:

"f000000339121"

domain
string

The company's domain. Send this or company_id, not both.

Example:

"pgim.com"

external_id
string

Your own ID, returned in input

Maximum string length: 200

Response

One answer, or a batch with results

input
object

What you sent for this company, including any external_id

Example:
company
object | null

The company's AI adoption, or null when Firmable has none

evidence
object

One entry per area that has evidence

error
object

Set when the company isn't found

usage
object