Skip to main content
POST

Description

Answers a yes or no question about a company or a person with one decision tool. Ask about one subject, or about up to 100 in a batch. Every answer is yes, no or unknown. unknown means Firmable doesn’t hold the fact. Never treat it as no. Get the tool names, inputs and examples from List Decision Tools. See Decisions for the full guide.

Request body

The body takes only tool and question. Any other field returns 400, including inputs placed next to tool instead of inside question. A company is identified by company_id or domain, and a person by person_id, linkedin_url or work_email.

One subject

A batch

A batch returns the top-level tool, request_id and version, a results array with one answer per row, and usage.billable_rows. Each row has the same fields as a single answer, plus your external_id. A row that can’t be answered carries an error; the other rows still come back.

Response

A single answer has tool, request_id, version, decision (yes, no or unknown), confidence (0 to 1), details (facts whose fields depend on the tool), entity (who it’s about), data_as_of, advisory (true for answers about people), usage.billable and error. See Decisions for an example and every field.

Reasoning

Add ?withReasoning=true to get a reasoning object with each answer: reason, text, source, date, date_label (such as last refreshed), would_change_if (a list) and unknown_reason (null unless the answer is unknown). It costs twice as much. The value must be true or false, and it can’t go in the body.

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 asking, Firmable checks your organisation has enough credits to pay for every row as if each were a yes or no answer. 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 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

withReasoning
boolean
default:false

true adds a reasoning object to each answer, at twice the price. Must be true or false. Can't be sent in the body.

Body

application/json
tool
string
required

The decision tool's name, from GET /decisions.

Required string length: 1 - 100
Example:

"is_b2b"

question
object
required

Who the question is about (company_id or domain; person_id, linkedin_url or work_email) and any inputs the tool needs, as in its input_schema. For a batch, put the subjects in records and the tool's other inputs next to records.

Response

One answer, or a batch with results

tool
string
Example:

"is_b2b"

request_id
string

The request's ID. Quote it if you contact support.

version
string

The version of the decision tools that answered.

Example:

"2026-11-06"

external_id
string

On a batch row: your own ID, as sent.

decision
enum<string>

The answer. unknown means Firmable doesn't hold the fact; it is not no.

Available options:
yes,
no,
unknown
confidence
number

How sure the answer is.

Required range: 0 <= x <= 1
Example:

0.99

details
object

Facts behind the answer. Its fields depend on the tool.

Example:
entity
object

Who the answer is about.

data_as_of
string<date>

The date of the data the answer used.

Example:

"2026-10-29"

advisory
boolean

true when the answer is a guide rather than a firm fact. Answers about people are advisory.

reasoning
object

Only with withReasoning=true.

usage
object
error
object | null

null, or what went wrong for this answer. Answers with an error are not charged.