> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decisions

> Ask yes or no questions about companies and people

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`.

> [!WARNING]
>
> `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:

* **Customer keys** start with `fbl_`. See [Creating API keys](https://docs.firmable.com/api-reference/creating-api-keys.md).
  They spend your subscription credits first, then add-on credits.
* **Developer keys** start with `fbl_dev_`. See [API keys and authentication](https://docs.firmable.com/developer/api-keys.md).
  They spend [developer credits](https://docs.firmable.com/developer/credits.md).

Send the key as a bearer token, as with every Firmable endpoint:

```bash theme={null}
-H "Authorization: Bearer fbl_your_key"
```

## Find the tool names

`GET /decisions` lists every decision tool that is switched on. It's free.

```bash theme={null}
curl "https://api.firmable.com/decisions" \
  -H "Authorization: Bearer fbl_your_key"
```

```json theme={null}
{
  "version": "2026-11-06",
  "tools": [
    {
      "name": "is_b2b",
      "summary": "Does the company sell to other businesses?",
      "subject": "company",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "company_id": { "type": "string" },
          "domain": { "type": "string" },
          "external_id": { "type": "string" }
        }
      },
      "example": { "company_id": "f000002437529" }
    }
  ]
}
```

Each tool has:

| Field | What it is |
| - | - |
| `name` | The tool's name. Send it as `tool` when you ask a question. |
| `summary` | The question the tool answers. |
| `subject` | Who it's about: `company`, `person`, or `company or person`. |
| `input_schema` | A JSON Schema for the tool's `question`. It accepts no other fields. |
| `example` | A valid `question` for the tool. Start from this. |

> [!NOTE]
>
> 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`:

| Subject | Identifiers |
| - | - |
| Company | `company_id` (a Firmable company ID, such as `f000002437529`) or `domain` (such as `linfox.com`) |
| Person | `person_id` (a Firmable person ID), `linkedin_url` or `work_email` |

## Ask one question

`POST /decisions` with the tool's name and its `question`:

```bash theme={null}
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" }
  }'
```

```json theme={null}
{
  "tool": "is_b2b",
  "request_id": "req_606c…",
  "version": "2026-11-06",
  "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",
    "caveat": null,
    "matched_by": "firmable_id",
    "employer": null
  },
  "data_as_of": "2026-10-29",
  "advisory": false,
  "usage": { "billable": true },
  "error": null
}
```

| Field | What it is |
| - | - |
| `tool` | The decision tool that answered. |
| `request_id` | The request's ID. Quote it if you contact support. |
| `version` | The version of the decision tools that answered. |
| `decision` | `yes`, `no` or `unknown`. |
| `confidence` | How sure the answer is, from 0 to 1. |
| `details` | Facts behind the answer. Its fields depend on the tool. |
| `entity` | Who the answer is about: `type` (`company` or `person`), Firmable `id`, `name`, `country`, `profile_url` (the profile in the Firmable app), and `matched_by` (which identifier found it). `caveat` and `employer` can be `null`; when set, they add context about the match. |
| `data_as_of` | The date of the data the answer used. |
| `advisory` | `true` when the answer is a guide rather than a firm fact. Answers about people are advisory. |
| `usage.billable` | `true` when the answer counts towards credits. |
| `error` | `null`, or what went wrong for this answer. |

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:

```json theme={null}
{
  "tool": "offers_service",
  "question": { "domain": "linfox.com", "service": "cold chain logistics" }
}
```

```json theme={null}
{
  "tool": "works_at_company",
  "question": { "linkedin_url": "https://www.linkedin.com/in/jane-citizen", "company_id": "f000002437529" }
}
```

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.

```bash theme={null}
curl -X POST "https://api.firmable.com/decisions" \
  -H "Authorization: Bearer fbl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "is_b2b",
    "question": {
      "records": [
        { "company_id": "f000002437529", "external_id": "row-1" }
      ]
    }
  }'
```

For a tool with its own inputs, put them next to `records`, for example
`"question": { "service": "cold chain logistics", "records": [ ... ] }` for `offers_service`.

```json theme={null}
{
  "tool": "is_b2b",
  "request_id": "req_606c…",
  "version": "2026-11-06",
  "results": [
    {
      "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",
        "caveat": null,
        "matched_by": "firmable_id",
        "employer": null
      },
      "tool": "is_b2b",
      "request_id": "req_606c…",
      "external_id": "row-1",
      "data_as_of": "2026-10-29",
      "advisory": false,
      "version": "2026-11-06",
      "usage": { "billable": true },
      "error": null
    }
  ],
  "usage": { "billable_rows": 1 }
}
```

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.

```bash theme={null}
curl -X POST "https://api.firmable.com/decisions?withReasoning=true" \
  -H "Authorization: Bearer fbl_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "is_b2b", "question": { "company_id": "f000002437529" } }'
```

Each answer then has a `reasoning` object, next to its other fields:

```json theme={null}
"reasoning": {
  "reason": "We invest in people, property, assets and systems to develop market leading supply chains…",
  "text": "We invest in people, property, assets and systems to develop market leading supply chains…",
  "source": "Firmable company data",
  "date": "2026-10-29",
  "date_label": "last refreshed",
  "would_change_if": [],
  "unknown_reason": null
}
```

| Field | What it is |
| - | - |
| `reason` | The evidence behind the answer. |
| `text` | The evidence as text. It can repeat `reason`. |
| `source` | Where the evidence came from. |
| `date` | The date that goes with the evidence. |
| `date_label` | What `date` is, such as `last refreshed`. |
| `would_change_if` | A list of what would change the answer. Can be empty. |
| `unknown_reason` | `null`, unless the answer is `unknown`: then why Firmable couldn't answer. |

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.

| What | Credits |
| - | - |
| `GET /decisions` | Free |
| Yes or no answers | 1 credit per 25 answers |
| Yes or no answers with `withReasoning=true` | 2 credits per 25 answers |
| `unknown` answers, rows with an `error`, failed requests | 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:

```json theme={null}
{
  "error": {
    "code": "tool_not_found",
    "message": "No decision tool named 'is_btob'. GET /decisions lists them.",
    "docs_url": "/decisions"
  }
}
```

See [Make a decision](https://docs.firmable.com/api-reference/endpoint/decisions-make.md#errors) 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](https://docs.firmable.com/mcp/decisions.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.