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

# AI Adoption

> See how far a company has adopted AI

The AI Adoption API tells you how far a company has adopted AI. For each company you get an overall
level, a one-line explanation, its momentum, and a score for five areas:

| Area | What it looks at |
| - | - |
| `architecture` | AI and data technology the company builds with, such as model serving, data pipelines and containers. |
| `footprint` | AI tools the company uses, such as AI assistants and coding assistants. |
| `hiring` | AI roles the company has advertised. |
| `initiatives` | News and posts about the company's AI work. |
| `workforce` | People in AI roles at the company, and how senior they are. |

Add `withEvidence=true` to also get the evidence behind each area: the technologies, job ads, posts
and people Firmable found.

## Who can use it

Both kinds of API key work, with the same endpoint, 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"
```

## Which company

Give one identifier for the company:

| Identifier | Example |
| - | - |
| `company_id` | A Firmable company ID, such as `f000000339121` |
| `domain` | The company's domain, such as `pgim.com` |

Send exactly one. Sending both, or neither, returns `400`.

## Get one company

`POST /ai-adoption` with the company in the body:

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

```json theme={null}
{
  "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", … },
      "footprint": { "level": "BASIC", "headline": "1 of 9 categories: General AI assistants · Claude (Anthropic)", … },
      "hiring": { "level": "BASIC", "headline": "3 AI roles in 12 months · none in the last 90 days · 1 leadership · latest Oct 2026", … },
      "initiatives": { "level": "NONE", "headline": null, … },
      "workforce": { "level": "STRONG", "headline": "AI leadership in place · 11 AI specialists, 6 senior · highest level VP/Director", … }
    },
    "evidence_available": {
      "architecture": 33,
      "footprint": 3,
      "hiring": 3,
      "initiatives": 5,
      "workforce": 20
    },
    "as_of": "2026-11-10",
    "framework_version": "2026.10"
  },
  "usage": { "billable": true }
}
```

| Field | What it is |
| - | - |
| `input` | What you sent for this company, including any `external_id`. |
| `company` | The company's AI adoption, or `null` when Firmable has none for it. |
| `company.firmable_id`, `company_name`, `country`, `industry_group`, `size_band` | Who the company is. `country` and `industry_group` can be missing. |
| `company.overall_level` | The company's overall AI adoption level, such as `NONE`, `BASIC`, `MODERATE`, `STRONG` or `ADVANCED`. |
| `company.explanation` | One sentence on why the company has that level. |
| `company.momentum` | Whether adoption is growing: a `label`, such as `EXPANDING`, and the recent `signals` behind it, each with a `kind`, a `count` and the `latest` date. |
| `company.dimensions` | The five areas, each with its own `level` and `headline`. See [Areas](#areas). |
| `company.evidence_available` | How many evidence items Firmable holds for each area. `0` means none. |
| `company.as_of` | The date of the data. |
| `company.framework_version` | The version of the scoring rules that produced the levels. |
| `usage.billable` | `true` when the company counts towards credits. |

Responses can carry other fields too. Ignore the ones you don't use.

> [!NOTE]
>
> Levels are words, such as `NONE`, `BASIC`, `MEANINGFUL`, `MODERATE`, `STRONG` or `ADVANCED`. New
> levels can be added, so don't fail on a level you don't recognise.

## Areas

Every area in `company.dimensions` has:

| Field | What it is |
| - | - |
| `level` | The area's level. |
| `headline` | A short summary of what Firmable found, or `null` when there's nothing to say. |
| `observability` | How much Firmable can see of this area for this company, such as `LOW`, `MEDIUM` or `HIGH`. |
| `counts_toward_overall` | `true` when the area counts towards `overall_level`. |

Each area adds its own detail:

| Area | Detail |
| - | - |
| `architecture`, `footprint` | `groups`, the technology groups seen, and `sub_dimensions`: one row per category with `category`, `present`, `technologies` (how many were seen) and `top` (the main one, or `null`). |
| `hiring` | `sub_dimensions` with `hiring_scale` (`roles_12m`, `roles_90d`), `leadership_hiring` (`leadership_roles`), `concentration` (`ai_share_of_postings`, the share of job ads that are AI roles) and `recency` (`latest_posting`). |
| `initiatives` | `counts`: `signals` (posts found) and `qualifying` (posts that count towards the level). |
| `workforce` | `sub_dimensions` with `specialist_scale` (`specialists`, `senior_specialists`), `leadership_presence` (`present`, `leaders`, `top_title`), `capability_seniority` (`breadth`, `height`), `concentration` (`ai_share`, `observable_people`), `movement` (`joiners_12m`) and `skills_evidence` (`people_with_ai_skills`). |

## Get many at once

To get up to 100 companies in one call, put them in `records`. Add your own `external_id` to a row to
match the answer back to your data. Each row takes `company_id` or `domain`, and rows can mix them.

```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": "unknown-company.example", "external_id": "row-2" }
    ]
  }'
```

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

`results` has one row per company, in the order you sent them. Each row has the same fields as a
single answer. `usage.billable_rows` counts the rows you pay for.

## When a company isn't found

If Firmable has no AI adoption data for a company, or can't match the domain, the answer still comes
back with `200`. `company` is `null`, `error.code` is `not_found`, and it's free. In a batch, the
other rows still come back.

## Get the evidence

Add `withEvidence=true` to the URL to also get the evidence behind each area. It's a query
parameter, not part of the body.

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

Each answer then has an `evidence` object next to `company`, with one entry per area:

```json theme={null}
"evidence": {
  "hiring": {
    "as_of": "2026-11-05",
    "framework_version": "2026.10",
    "item_count": 3,
    "truncated": false,
    "items": [
      {
        "ref": { "type": "signal", "id": "fsf7be3eeb41fbfd0b794e2c6f11c5c8f0" },
        "title": "Director, AI Tech Lead - PGIM Technology (Hybrid - Newark, NJ)",
        "type": "AI_LEADERSHIP_ROLE",
        "date": "2026-10-13",
        "qualifies": true
      }
    ]
  },
  "architecture": { … },
  "footprint": { … },
  "initiatives": { … },
  "workforce": { … }
}
```

| Field | What it is |
| - | - |
| `as_of` | The date of the area's evidence. |
| `framework_version` | The version of the scoring rules. |
| `item_count` | How many items Firmable holds for the area. |
| `truncated` | `true` when `items` doesn't hold all of them. |
| `items` | The evidence. Each item has a `ref` (`type` and `id`) and `qualifies`: `true` when it counts towards the area's level. |

Items in each area also have:

| Area | Item fields |
| - | - |
| `architecture` | `technology`, `category`, `catalogue_category`, `sources`, `first_seen`, `last_seen`, `observation` (such as `DIRECT` or `INFERRED`), `confidence_band` and `state` (such as `CURRENT`, `AGEING` or `DORMANT`). |
| `footprint` | The same as `architecture`, with `group` instead of `catalogue_category`. |
| `hiring` | `title`, `type` (such as `AI_LEADERSHIP_ROLE`) and `date`. |
| `initiatives` | `summary`, `publisher`, `type`, `date`, `related` (a list of `ref`s) and `confidence_band`. |
| `workforce` | `title`, `type`, `seniority`, `first_seen`, `confidence_band` and `state`. `ref.id` is the person's Firmable person ID. |

`confidence_band` is a band such as `LOW`, `MEDIUM` or `HIGH`. New values can be added, as with levels.

An area with no evidence is left out of `evidence`. A company with no evidence at all has no
`evidence` field. Check `company.evidence_available` to see what each area holds.

`withEvidence` must be `true` or `false`; anything else returns `400`.

## Pricing

You pay only for companies Firmable has data for.

| What | Credits |
| - | - |
| A company found | 1 credit per 5 companies |
| A company found with evidence, using `withEvidence=true` | 3 credits per company |
| A company not found, failed requests | Free |

* **A batch is charged per row.** A batch of 100 with 80 companies found counts 80.
* **Evidence is charged only when some comes back.** With `withEvidence=true`, a company found with
  no evidence costs the same as one without evidence.
* **Part-credits carry over.** Companies add up across requests, and a credit is taken each time
  your organisation reaches 5. Two companies today and three 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 reading anything, Firmable checks your organisation
  could pay if every company were found: at least 1 credit for one company, 20 for a batch of 100,
  3 for one company with evidence, or 300 for a batch of 100 with evidence. 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": "invalid_request",
    "message": "withEvidence: must be true or false",
    "docs_url": "/ai-adoption"
  }
}
```

See [Get AI Adoption](https://docs.firmable.com/api-reference/endpoint/ai-adoption-get.md#errors) for every status and code.

## Using an AI agent

The Firmable MCP server has a `get_ai_adoption` tool that returns the same data. See
[AI Adoption tool](https://docs.firmable.com/mcp/ai-adoption.md).


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