curl --request POST \
--url https://api.firmable.com/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tool": "is_b2b",
"question": {
"company_id": "f000002437529"
}
}
'{
"tool": "is_b2b",
"request_id": "<string>",
"version": "2026-11-06",
"external_id": "<string>",
"decision": "yes",
"confidence": 0.99,
"details": {
"sells_to": "businesses"
},
"entity": {
"type": "company",
"id": "f000002437529",
"name": "Linfox",
"country": "AU",
"profile_url": "https://app.firmable.com/dashboard/company/f000002437529",
"matched_by": "firmable_id",
"caveat": "<string>",
"employer": {}
},
"data_as_of": "2026-10-29",
"advisory": true,
"reasoning": {
"reason": "<string>",
"text": "<string>",
"source": "Firmable company data",
"date": "2026-10-29",
"date_label": "last refreshed",
"would_change_if": [
"<string>"
],
"unknown_reason": "<string>"
},
"usage": {
"billable": true
},
"error": {}
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}Decisions API
Make a Decision
Answers a yes or no question about a company or a person with one decision tool, for one subject or up to 100 records. Each answer is yes, no or unknown; unknown means Firmable doesn’t hold the fact, not no. Costs 1 credit per 25 yes or no answers, or 2 per 25 with withReasoning=true. Unknown answers, rows with an error and failed requests are free.
POST
/
decisions
curl --request POST \
--url https://api.firmable.com/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tool": "is_b2b",
"question": {
"company_id": "f000002437529"
}
}
'{
"tool": "is_b2b",
"request_id": "<string>",
"version": "2026-11-06",
"external_id": "<string>",
"decision": "yes",
"confidence": 0.99,
"details": {
"sells_to": "businesses"
},
"entity": {
"type": "company",
"id": "f000002437529",
"name": "Linfox",
"country": "AU",
"profile_url": "https://app.firmable.com/dashboard/company/f000002437529",
"matched_by": "firmable_id",
"caveat": "<string>",
"employer": {}
},
"data_as_of": "2026-10-29",
"advisory": true,
"reasoning": {
"reason": "<string>",
"text": "<string>",
"source": "Firmable company data",
"date": "2026-10-29",
"date_label": "last refreshed",
"would_change_if": [
"<string>"
],
"unknown_reason": "<string>"
},
"usage": {
"billable": true
},
"error": {}
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
},
"request_id": "<string>"
}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 isyes, 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
| Field | What it is |
|---|---|
tool | The decision tool’s name, such as is_b2b. |
question | Who the question is about, plus any inputs the tool needs. It must match the tool’s input_schema. |
question.records | Optional. Up to 100 rows, each with who it’s about and an optional external_id. Every row gets the same question. |
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
curl -X POST "https://api.firmable.com/decisions" \
-H "Authorization: Bearer fbl_your_key" \
-H "Content-Type: application/json" \
-d '{ "tool": "is_b2b", "question": { "company_id": "f000002437529" } }'
A batch
curl -X POST "https://api.firmable.com/decisions" \
-H "Authorization: Bearer fbl_your_key" \
-H "Content-Type: application/json" \
-d '{
"tool": "offers_service",
"question": {
"service": "cold chain logistics",
"records": [
{ "domain": "linfox.com", "external_id": "row-1" }
]
}
}'
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 hastool, 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
| Answer | Credits |
|---|---|
| Yes or no | 1 per 25 answers |
Yes or no, with withReasoning=true | 2 per 25 answers |
unknown, rows with an error, failed requests | Free |
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:{
"error": {
"code": "invalid_request",
"message": "withReasoning: must be true or false",
"docs_url": "/decisions"
}
}
| Status | Code | When |
|---|---|---|
400 | invalid_request | No tool, no question, a field outside tool and question, more than 100 records, withReasoning that isn’t true or false, or an input the tool doesn’t accept or needs. The message names the field |
401 | unauthorized | A missing or invalid API key |
402 | insufficient_credits | Your organisation hasn’t enough credits for every row to be a yes or no answer |
403 | forbidden | The key can’t use this endpoint |
404 | tool_not_found | No decision tool has that name. Check List Decision Tools |
429 | Too many requests. Wait for the number of seconds in the retry-after header | |
500 | Something went wrong. Try again | |
502 | upstream_error | The decision service is unavailable. Try again shortly |
Authorizations
Query Parameters
Body
application/json
Response
One answer, or a batch with results
- Option 1
- Option 2