# Firmable for agents

> Verified company and people data for AI agents. One developer key works for the REST API and the Firmable MCP server.

## Set yourself up

- Quickest: read https://agents.firmable.com/developer/setup.txt and follow the steps for the agent you are running in.
- MCP server: https://agents.firmable.com/developer/mcp (Streamable HTTP).
- OAuth: client ID `rkI2RHxS55F7qKp8`, callback port 53612 (http://localhost:53612/oauth/callback). Use this on a person's own machine.
- API key: send `Authorization: Bearer <key>` instead. Use this on a server or in CI.
- Keys: a person creates one at https://platform.firmable.com/sign-up. Developer keys start with `fbl_dev_`. Ask the person for it; never print it back.
- Setup steps for each client: https://docs.firmable.com/api-reference/overview

## MCP tools

- `filter_search`: Find companies or people by industry, location, size, seniority, department and more. Cost: Free.
- `ai_search`: Find companies or people from a plain-English description. Cost: Free.
- `get_company`: A full company profile from a domain, LinkedIn URL or Firmable ID. Cost: 1 credit a new profile.
- `get_person`: Resolve a person from an email, LinkedIn URL or Firmable ID. Cost: 1 credit a new profile.
- `make_decision`: Yes, no or unknown about a company or person, with the facts behind it. Cost: 1 credit per 25 yes or no answers, 2 with reasoning. Unknown answers are free.
- `list_decision_tools`: The decision tools that are switched on, with the inputs each one needs. Cost: Free.
- `get_tech_intel`: The technologies a company runs, with confidence and recency. Cost: Up to 5 credits a company, once.
- `bulk_get_tech_intel`: Technologies for up to 200 companies, 20 each. Cost: Up to 5 credits a company, once.
- `get_ai_adoption`: A company's AI adoption level, momentum and five areas. Cost: 1 credit per 5 companies found, 3 per company with evidence. Not found is free.

## REST API

Base URL: https://api.firmable.com

- `GET /company`: Company enrichment by id, ln_slug, ln_url, fqdn, website or abn. Optional country.
- `GET /people`: People enrichment by id, ln_slug, ln_url, work_email or personal_email.
- `POST /people/search`: Search by companyId, position, seniority and department, with from and size for paging.
- `GET /filter-options`: The filter codes the search endpoints accept, and the markets a search can cover. Not charged.
- `GET /tech-intel`: Tech Intelligence by id, ln_url, ln_slug, fqdn, website or abn. 100 a page with a cursor.
- `GET /decisions`: The decision tools that are switched on, with each one's inputs and an example. Free.
- `POST /decisions`: A yes, no or unknown answer about a company or person, for one or up to 100 records. Add withReasoning=true for the reasoning.
- `POST /ai-adoption`: How far a company has adopted AI, for one or up to 100 companies. Add withEvidence=true for the evidence.

OpenAPI spec: https://docs.firmable.com/api-reference/openapi.json

## Rules that matter

- A Decisions answer of `unknown` means Firmable doesn't hold the fact. It is not a no.
- Decision tools change without notice. Read `list_decision_tools` or `GET /decisions` rather than hard-coding names.
- Answers about people come back with `advisory: true`: a guide, not a firm fact.
- Reasoning (`withReasoning`) and evidence (`withEvidence`) cost more. Ask for them only when you need them.
- 15 requests a second per key. `402` means the organization is out of credits; `429` means slow down.

## Credits

- 100 free credits on sign-up (worth US$25), for the first sign-up from each company, plus 40 on the 1st of every month.
- 1 credit per new company or person profile, once. Search is free.
- Decisions: 1 credit per 25 answers, 2 per 25 with reasoning. Unknown answers are free.
- Tech Intelligence: 1 credit per technology, up to 5 per company, once.
- AI adoption: 1 credit per 5 companies found, 3 per company with evidence. Companies not found are free.
- Details: https://docs.firmable.com/api-reference/overview

## More

- Full docs: https://docs.firmable.com/api-reference/overview (index: https://docs.firmable.com/llms.txt)
- This site in one file: https://developer.firmable.ai/llms-full.txt
- Pricing: https://developer.firmable.ai/pricing
