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

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

## 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](https://docs.firmable.com/api-reference/endpoint/decisions-list.md).
See [Decisions](https://docs.firmable.com/api-reference/decisions.md) 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. |

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

```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" } }'
```

### A batch

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

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](https://docs.firmable.com/api-reference/decisions.md#ask-one-question) 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 |

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](https://docs.firmable.com/developer/credits.md).

## Errors

Errors have this shape:

```json theme={null}
{
  "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](https://docs.firmable.com/api-reference/endpoint/decisions-list.md) |
| `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 |

Failed requests are never charged.


## OpenAPI

````yaml POST /decisions
openapi: 3.0.1
info:
  title: Firmable API
  description: >-
    The Firmable API provides access to company and people data across multiple
    countries including Australia, New Zealand, Singapore, Malaysia, Indonesia,
    Philippines, Hong Kong, Japan, Vietnam, South Korea, Thailand, United
    States, and Canada. Use it to look up company profiles, retrieve contact
    information, and search for people by company, position, seniority, and
    department.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.firmable.com
security:
  - bearerAuth: []
paths:
  /decisions:
    post:
      description: >-
        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.
      parameters:
        - name: withReasoning
          in: query
          description: >-
            true adds a reasoning object to each answer, at twice the price.
            Must be true or false. Can't be sent in the body.
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
            examples:
              single:
                summary: One company
                value:
                  tool: is_b2b
                  question:
                    company_id: f000002437529
              withInputs:
                summary: A tool with its own input
                value:
                  tool: offers_service
                  question:
                    domain: linfox.com
                    service: cold chain logistics
              batch:
                summary: A batch
                value:
                  tool: is_b2b
                  question:
                    records:
                      - company_id: f000002437529
                        external_id: row-1
      responses:
        '200':
          description: One answer, or a batch with results
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Decision'
                  - $ref: '#/components/schemas/DecisionBatch'
        '400':
          description: >-
            invalid_request: a missing tool or question, a field outside tool
            and question, more than 100 records, a withReasoning that isn't true
            or false, or an input the tool doesn't accept or needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
        '402':
          description: >-
            insufficient_credits: not enough credits for every row to be a yes
            or no answer. Nothing is charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
        '403':
          description: The key can't use this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
        '404':
          description: 'tool_not_found: no decision tool has that name'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
        '429':
          description: >-
            Too many requests. Wait for the number of seconds in the retry-after
            header
        '502':
          description: >-
            upstream_error: the decision service is unavailable. Try again
            shortly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionError'
components:
  schemas:
    DecisionRequest:
      type: object
      required:
        - tool
        - question
      additionalProperties: false
      properties:
        tool:
          type: string
          minLength: 1
          maxLength: 100
          description: The decision tool's name, from GET /decisions.
          example: is_b2b
        question:
          type: object
          description: >-
            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.
          additionalProperties: true
          properties:
            records:
              type: array
              minItems: 1
              maxItems: 100
              description: Up to 100 companies or people to ask the same question about.
              items:
                type: object
                description: >-
                  Who this row is about, and optionally your own external_id,
                  returned with the row's answer.
                additionalProperties: true
    Decision:
      type: object
      properties:
        tool:
          type: string
          example: is_b2b
        request_id:
          type: string
          description: The request's ID. Quote it if you contact support.
        version:
          type: string
          description: The version of the decision tools that answered.
          example: '2026-11-06'
        external_id:
          type: string
          description: 'On a batch row: your own ID, as sent.'
        decision:
          type: string
          enum:
            - 'yes'
            - 'no'
            - unknown
          description: >-
            The answer. unknown means Firmable doesn't hold the fact; it is not
            no.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: How sure the answer is.
          example: 0.99
        details:
          type: object
          description: Facts behind the answer. Its fields depend on the tool.
          example:
            sells_to: businesses
        entity:
          type: object
          description: Who the answer is about.
          properties:
            type:
              type: string
              enum:
                - company
                - person
            id:
              type: string
              description: Firmable ID
              example: f000002437529
            name:
              type: string
              example: Linfox
            country:
              type: string
              example: AU
            profile_url:
              type: string
              description: The profile in the Firmable app.
              example: https://app.firmable.com/dashboard/company/f000002437529
            matched_by:
              type: string
              description: Which identifier found the company or person.
              example: firmable_id
            caveat:
              type: string
              nullable: true
              description: Context about the match, when there is any.
            employer:
              type: object
              nullable: true
              description: Context about the employer, when there is any.
        data_as_of:
          type: string
          format: date
          description: The date of the data the answer used.
          example: '2026-10-29'
        advisory:
          type: boolean
          description: >-
            true when the answer is a guide rather than a firm fact. Answers
            about people are advisory.
        reasoning:
          $ref: '#/components/schemas/DecisionReasoning'
        usage:
          type: object
          properties:
            billable:
              type: boolean
              description: true when this answer counts towards credits.
        error:
          type: object
          nullable: true
          description: >-
            null, or what went wrong for this answer. Answers with an error are
            not charged.
    DecisionBatch:
      type: object
      properties:
        tool:
          type: string
          example: is_b2b
        request_id:
          type: string
        version:
          type: string
          example: '2026-11-06'
        results:
          type: array
          description: One answer per record, each with the external_id sent.
          items:
            $ref: '#/components/schemas/Decision'
        usage:
          type: object
          properties:
            billable_rows:
              type: integer
              description: How many rows count towards credits.
              example: 1
    DecisionError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: 'withReasoning: must be true or false'
            docs_url:
              type: string
              example: /decisions
        request_id:
          type: string
    DecisionReasoning:
      type: object
      description: Only with withReasoning=true.
      properties:
        reason:
          type: string
          description: The evidence behind the answer.
        text:
          type: string
          description: The evidence as text. It can repeat reason.
        source:
          type: string
          description: Where the evidence came from.
          example: Firmable company data
        date:
          type: string
          description: The date that goes with the evidence.
          example: '2026-10-29'
        date_label:
          type: string
          description: What date is.
          example: last refreshed
        would_change_if:
          type: array
          items:
            type: string
          description: What would change the answer. Can be empty.
        unknown_reason:
          type: string
          nullable: true
          description: >-
            null unless the answer is unknown: then why Firmable couldn't
            answer.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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