Skip to main content
The Decisions API answers yes or no questions about a company or a person from Firmable data. For example: Is this company B2B?, Does it offer cold chain logistics? or Does this person work at this company? Each kind of question is a decision tool with a name, such as is_b2b, and its own inputs. You pick a tool, say who the question is about, and get an answer. Every answer is yes, no or unknown.
unknown means Firmable doesn’t hold the fact needed to answer. It is not a no. Never treat an unknown answer as no.

Who can use it

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

Find the tool names

GET /decisions lists every decision tool that is switched on. It’s free.
Each tool has:
Tools are added and changed without notice. Read the list from GET /decisions rather than hard-coding tool names or inputs.

Who the question is about

Put one identifier for the company or person in the question:

Ask one question

POST /decisions with the tool’s name and its question:
Responses can carry other fields too. Ignore the ones you don’t use. Some tools need more than who the question is about. offers_service needs the service to check, and works_at_company needs a person plus the company_id to check against:
The tool’s input_schema lists what it accepts, and its example shows a valid question. If an input is missing or wrong, the call returns 400 and the message names the field.

Ask about many at once

To ask the same question about up to 100 companies or people, put them in question.records. Any other inputs the tool needs go next to records and apply to every row. Add your own external_id to a row to match the answer back to your data.
For a tool with its own inputs, put them next to records, for example "question": { "service": "cold chain logistics", "records": [ ... ] } for offers_service.
Each row in results has the same fields as a single answer, plus the external_id you sent. usage.billable_rows counts the rows you pay for. Each row is answered on its own: a row that can’t be answered carries an error, and the others still come back.

Get the reasoning

Add withReasoning=true to the URL to get the reasoning behind each answer. It’s a query parameter, not part of the body, and it costs twice as much.
Each answer then has a reasoning object, next to its other fields:
In a batch, each row in results has its own reasoning. Without withReasoning, answers carry no reasoning. withReasoning must be true or false; anything else returns 400.

Pricing

You pay only for answers. Listing tools is free.
  • A batch is charged per row. A batch of 100 with 80 yes or no answers counts 80.
  • Part-credits carry over. Answers add up across requests, and a credit is taken each time your organisation reaches 25. Ten answers today and 15 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 asking, Firmable checks your organisation could pay if every row were a yes or no answer: at least 1 credit for one question, 4 for a batch of 100, or 8 for a batch of 100 with reasoning. If not, the call returns 402 insufficient_credits and nothing is charged.

Errors

Errors return a status code and a JSON body:
See Make a decision for every status and code.

Using an AI agent

The Firmable MCP server has two tools for this: make_decision, which takes a question in plain English and picks the decision tool for you, and list_decision_tools. See Decision tools.