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.
Who can use it
Both kinds of API key work, with the same endpoints, 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.
Find the tool names
GET /decisions lists every decision tool that is switched on. It’s free.
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 thequestion:
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:
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 inquestion.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.
records, for example
"question": { "service": "cold chain logistics", "records": [ ... ] } for offers_service.
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
AddwithReasoning=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.
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.billableistrueon an answer you pay for. A batch also returnsusage.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_creditsand nothing is charged.
Errors
Errors return a status code and a JSON body: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.