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

# Get AI Adoption

> Returns how far a company has adopted AI

## Description

Returns how far a company has adopted AI: an overall level, a one-line explanation, momentum, and a
level for each of five areas (`architecture`, `footprint`, `hiring`, `initiatives`, `workforce`).
Ask about one company, or up to 100 in a batch.

See [AI Adoption](https://docs.firmable.com/api-reference/ai-adoption.md) for the full guide.

## Request body

| Field | What it is |
| - | - |
| `company_id` | A Firmable company ID, such as `f000000339121`. |
| `domain` | The company's domain, such as `pgim.com`. |
| `external_id` | Optional. Your own ID, up to 200 characters, returned in `input`. |
| `records` | Optional. Up to 100 rows, each with `company_id` or `domain` and an optional `external_id`. Send it instead of the fields above, not with them. |

Each company takes exactly one of `company_id` or `domain`. Any other field returns `400`.

### One company

```bash theme={null}
curl -X POST "https://api.firmable.com/ai-adoption" \
  -H "Authorization: Bearer fbl_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "company_id": "f000000339121" }'
```

### A batch

```bash theme={null}
curl -X POST "https://api.firmable.com/ai-adoption" \
  -H "Authorization: Bearer fbl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "company_id": "f000000339121", "external_id": "row-1" },
      { "domain": "linfox.com", "external_id": "row-2" }
    ]
  }'
```

A batch returns a `results` array with one answer per company, in the order sent, and
`usage.billable_rows`.

## Response

A single answer has `input` (what you sent), `company` (the AI adoption, or `null` when Firmable has
none) and `usage.billable`. A company that isn't found also has `error.code` set to `not_found`, and
still returns `200`. See [AI Adoption](https://docs.firmable.com/api-reference/ai-adoption.md#get-one-company) for an example and
every field.

## Evidence

Add `?withEvidence=true` to get an `evidence` object with each answer: one entry per area that has
evidence, each with `as_of`, `framework_version`, `item_count`, `truncated` and `items`. The value
must be `true` or `false`, and it can't go in the body. See
[Get the evidence](https://docs.firmable.com/api-reference/ai-adoption.md#get-the-evidence).

## Credits

| Answer | Credits |
| - | - |
| A company found | 1 per 5 companies |
| A company found with evidence | 3 per company |
| A company not found, 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 reading anything, Firmable checks your organisation has enough credits to pay for every row
as if each company were found. 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 from this endpoint have this shape:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "withEvidence: must be true or false",
    "docs_url": "/ai-adoption"
  }
}
```

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | No company, both `company_id` and `domain`, an unknown field, an empty `records` or more than 100, or `withEvidence` that isn't `true` or `false`. The message names the field |
| `401` | | A missing or invalid API key |
| `402` | `insufficient_credits` | Your organisation hasn't enough credits for every row to be found |
| `403` | `forbidden` | The key can't use this endpoint, such as a partner key |
| `500` | | Something went wrong. Try again |

Failed requests are never charged.


## OpenAPI

````yaml POST /ai-adoption
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:
  /ai-adoption:
    post:
      description: Returns how far a company has adopted AI
      parameters:
        - name: withEvidence
          in: query
          description: >-
            true adds an evidence object to each answer, at 3 credits per
            company with evidence. 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/AiAdoptionRequest'
            examples:
              single:
                summary: One company by ID
                value:
                  company_id: f000000339121
              domain:
                summary: One company by domain
                value:
                  domain: pgim.com
              batch:
                summary: A batch
                value:
                  records:
                    - company_id: f000000339121
                      external_id: row-1
                    - domain: linfox.com
                      external_id: row-2
      responses:
        '200':
          description: One answer, or a batch with results
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AiAdoption'
                  - $ref: '#/components/schemas/AiAdoptionBatch'
              examples:
                single:
                  summary: One company
                  value:
                    input:
                      company_id: f000000339121
                    company:
                      firmable_id: f000000339121
                      company_name: PGIM
                      country: US
                      industry_group: Financial services
                      size_band: ENTERPRISE
                      overall_level: STRONG
                      explanation: >-
                        AI workforce strong with dedicated AI leadership, basic
                        footprint across Workplace AI assistants, meaningful
                        architecture including Docker, AWS SageMaker, Amazon
                        ECS, basic AI hiring.
                      momentum:
                        label: EXPANDING
                        signals:
                          - count: 2
                            kind: AI hiring
                            latest: '2026-10-13'
                      dimensions:
                        architecture:
                          level: MEANINGFUL
                          headline: >-
                            4 of 14 capabilities: Serving, Data pipelines,
                            Containers, CI/CD · Docker, AWS SageMaker, Amazon
                            ECS
                          observability: HIGH
                          counts_toward_overall: true
                        footprint:
                          level: BASIC
                          headline: >-
                            1 of 9 categories: General AI assistants · Claude
                            (Anthropic)
                          observability: HIGH
                          counts_toward_overall: true
                        hiring:
                          level: BASIC
                          headline: >-
                            3 AI roles in 12 months · none in the last 90 days ·
                            1 leadership · latest Oct 2026
                          observability: HIGH
                          counts_toward_overall: true
                        initiatives:
                          level: NONE
                          headline: null
                          observability: HIGH
                          counts_toward_overall: true
                        workforce:
                          level: STRONG
                          headline: >-
                            AI leadership in place · 11 AI specialists, 6 senior
                            · highest level VP/Director
                          observability: HIGH
                          counts_toward_overall: true
                      evidence_available:
                        architecture: 33
                        footprint: 3
                        hiring: 3
                        initiatives: 5
                        workforce: 20
                      as_of: '2026-11-10'
                      framework_version: '2026.10'
                    usage:
                      billable: true
                batch:
                  summary: A batch (trimmed)
                  value:
                    results:
                      - input:
                          company_id: f000000339121
                          external_id: row-1
                        company:
                          firmable_id: f000000339121
                          company_name: PGIM
                          overall_level: STRONG
                        usage:
                          billable: true
                      - input:
                          domain: unknown-company.example
                          external_id: row-2
                        company: null
                        error:
                          code: not_found
                          message: No AI adoption data for this company
                        usage:
                          billable: false
                    usage:
                      billable_rows: 1
        '400':
          description: >-
            invalid_request: no company, both company_id and domain, an unknown
            field, an empty records or more than 100, or a withEvidence that
            isn't true or false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAdoptionError'
        '401':
          description: Missing or invalid API key
        '402':
          description: >-
            insufficient_credits: not enough credits for every row to be found.
            Nothing is charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAdoptionError'
        '403':
          description: 'forbidden: the key can''t use this endpoint, such as a partner key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAdoptionError'
        '500':
          description: Something went wrong. Try again
components:
  schemas:
    AiAdoptionRequest:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            company_id:
              type: string
              description: A Firmable company ID. Send this or domain, not both.
              example: f000000339121
            domain:
              type: string
              description: The company's domain. Send this or company_id, not both.
              example: pgim.com
            external_id:
              type: string
              maxLength: 200
              description: Your own ID, returned in input
        - type: object
          additionalProperties: false
          required:
            - records
          properties:
            records:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: object
                additionalProperties: false
                properties:
                  company_id:
                    type: string
                    description: A Firmable company ID. Send this or domain, not both.
                    example: f000000339121
                  domain:
                    type: string
                    description: The company's domain. Send this or company_id, not both.
                    example: pgim.com
                  external_id:
                    type: string
                    maxLength: 200
                    description: Your own ID, returned in input
    AiAdoption:
      type: object
      properties:
        input:
          type: object
          description: What you sent for this company, including any external_id
          additionalProperties: true
          example:
            company_id: f000000339121
        company:
          allOf:
            - $ref: '#/components/schemas/AiAdoptionCompany'
          nullable: true
          description: The company's AI adoption, or null when Firmable has none
        evidence:
          $ref: '#/components/schemas/AiAdoptionEvidence'
        error:
          type: object
          description: Set when the company isn't found
          properties:
            code:
              type: string
              enum:
                - not_found
            message:
              type: string
              example: No AI adoption data for this company
        usage:
          type: object
          properties:
            billable:
              type: boolean
    AiAdoptionBatch:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AiAdoption'
        usage:
          type: object
          properties:
            billable_rows:
              type: integer
    AiAdoptionError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: 'withEvidence: must be true or false'
            docs_url:
              type: string
              example: /ai-adoption
    AiAdoptionCompany:
      type: object
      properties:
        firmable_id:
          type: string
          example: f000000339121
        company_name:
          type: string
          example: PGIM
        country:
          type: string
          example: US
        industry_group:
          type: string
          example: Financial services
        size_band:
          type: string
          example: ENTERPRISE
        overall_level:
          type: string
          description: >-
            A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
            ADVANCED. New levels can be added.
          example: STRONG
        explanation:
          type: string
          description: Why the company has its overall level
        momentum:
          type: object
          properties:
            label:
              type: string
              example: EXPANDING
            signals:
              type: array
              items:
                type: object
                properties:
                  kind:
                    type: string
                    example: AI hiring
                  count:
                    type: integer
                    example: 2
                  latest:
                    type: string
                    example: '2026-10-13'
        dimensions:
          type: object
          properties:
            architecture:
              type: object
              description: >-
                One area's score. Each area adds its own detail (groups,
                sub_dimensions or counts).
              additionalProperties: true
              properties:
                level:
                  type: string
                  description: >-
                    A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
                    ADVANCED. New levels can be added.
                  example: STRONG
                headline:
                  type: string
                  nullable: true
                  description: A short summary of what Firmable found
                observability:
                  type: string
                  description: >-
                    How much Firmable can see of this area for the company, such
                    as LOW, MEDIUM or HIGH
                counts_toward_overall:
                  type: boolean
                  description: true when the area counts towards overall_level
            footprint:
              type: object
              description: >-
                One area's score. Each area adds its own detail (groups,
                sub_dimensions or counts).
              additionalProperties: true
              properties:
                level:
                  type: string
                  description: >-
                    A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
                    ADVANCED. New levels can be added.
                  example: STRONG
                headline:
                  type: string
                  nullable: true
                  description: A short summary of what Firmable found
                observability:
                  type: string
                  description: >-
                    How much Firmable can see of this area for the company, such
                    as LOW, MEDIUM or HIGH
                counts_toward_overall:
                  type: boolean
                  description: true when the area counts towards overall_level
            hiring:
              type: object
              description: >-
                One area's score. Each area adds its own detail (groups,
                sub_dimensions or counts).
              additionalProperties: true
              properties:
                level:
                  type: string
                  description: >-
                    A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
                    ADVANCED. New levels can be added.
                  example: STRONG
                headline:
                  type: string
                  nullable: true
                  description: A short summary of what Firmable found
                observability:
                  type: string
                  description: >-
                    How much Firmable can see of this area for the company, such
                    as LOW, MEDIUM or HIGH
                counts_toward_overall:
                  type: boolean
                  description: true when the area counts towards overall_level
            initiatives:
              type: object
              description: >-
                One area's score. Each area adds its own detail (groups,
                sub_dimensions or counts).
              additionalProperties: true
              properties:
                level:
                  type: string
                  description: >-
                    A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
                    ADVANCED. New levels can be added.
                  example: STRONG
                headline:
                  type: string
                  nullable: true
                  description: A short summary of what Firmable found
                observability:
                  type: string
                  description: >-
                    How much Firmable can see of this area for the company, such
                    as LOW, MEDIUM or HIGH
                counts_toward_overall:
                  type: boolean
                  description: true when the area counts towards overall_level
            workforce:
              type: object
              description: >-
                One area's score. Each area adds its own detail (groups,
                sub_dimensions or counts).
              additionalProperties: true
              properties:
                level:
                  type: string
                  description: >-
                    A level such as NONE, BASIC, MEANINGFUL, MODERATE, STRONG or
                    ADVANCED. New levels can be added.
                  example: STRONG
                headline:
                  type: string
                  nullable: true
                  description: A short summary of what Firmable found
                observability:
                  type: string
                  description: >-
                    How much Firmable can see of this area for the company, such
                    as LOW, MEDIUM or HIGH
                counts_toward_overall:
                  type: boolean
                  description: true when the area counts towards overall_level
        evidence_available:
          type: object
          description: Evidence items held per area. 0 means none.
          properties:
            architecture:
              type: integer
            footprint:
              type: integer
            hiring:
              type: integer
            initiatives:
              type: integer
            workforce:
              type: integer
        as_of:
          type: string
          description: The date of the data
          example: '2026-11-10'
        framework_version:
          type: string
          example: '2026.10'
    AiAdoptionEvidence:
      type: object
      description: One entry per area that has evidence
      properties:
        architecture:
          type: object
          properties:
            as_of:
              type: string
              example: '2026-11-05'
            framework_version:
              type: string
              example: '2026.10'
            item_count:
              type: integer
            truncated:
              type: boolean
              description: true when items doesn't hold all of them
            items:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  ref:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  qualifies:
                    type: boolean
                    description: true when the item counts towards the area's level
        footprint:
          type: object
          properties:
            as_of:
              type: string
              example: '2026-11-05'
            framework_version:
              type: string
              example: '2026.10'
            item_count:
              type: integer
            truncated:
              type: boolean
              description: true when items doesn't hold all of them
            items:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  ref:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  qualifies:
                    type: boolean
                    description: true when the item counts towards the area's level
        hiring:
          type: object
          properties:
            as_of:
              type: string
              example: '2026-11-05'
            framework_version:
              type: string
              example: '2026.10'
            item_count:
              type: integer
            truncated:
              type: boolean
              description: true when items doesn't hold all of them
            items:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  ref:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  qualifies:
                    type: boolean
                    description: true when the item counts towards the area's level
        initiatives:
          type: object
          properties:
            as_of:
              type: string
              example: '2026-11-05'
            framework_version:
              type: string
              example: '2026.10'
            item_count:
              type: integer
            truncated:
              type: boolean
              description: true when items doesn't hold all of them
            items:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  ref:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  qualifies:
                    type: boolean
                    description: true when the item counts towards the area's level
        workforce:
          type: object
          properties:
            as_of:
              type: string
              example: '2026-11-05'
            framework_version:
              type: string
              example: '2026.10'
            item_count:
              type: integer
            truncated:
              type: boolean
              description: true when items doesn't hold all of them
            items:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  ref:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  qualifies:
                    type: boolean
                    description: true when the item counts towards the area's level
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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