# Firmographic

> Company data for agents: companies, vendors, hiring, funding, website visitors and decision makers, through one API.

Base URL: https://api.firmographic.com
Auth: send your key as Authorization: Bearer fg_live_... (x-api-key also works). Create one at /keys in the dashboard.
MCP: https://api.firmographic.com/mcp (Streamable HTTP; an API key or OAuth). Tools match the routes below.
Every data response has the shape {data, meta: {records, credits_used, credits_left, next_cursor}}.
Errors have the shape {error: {code, message, fix}}. Read `fix` to correct the call.
A call that finds nothing costs nothing. Pass `fields` to keep responses small.

## Routes

### GET /v1/companies/{domain}

A company's profile: size, industry and location, with its lead score and the reasons for it. A domain we do not have returns 404 and costs nothing.
Credits: 1 credit per company found.
MCP tool: get_company
CLI: firmographic company northwind.example
- domain (path, required): The company's domain.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":{"city":"Chicago","country":"US","employees":"201-500","industry":"Transportation and Logistics","name":"Northwind Freight","region":"North America","source":"sample","updated_at":"2026-11-04T13:42:55.83Z","domain":"northwind.example","lead":{"score":60,"heat":"hot","reasons":["funding","hiring"]}},"meta":{"records":1,"credits_used":1,"credits_left":99,"next_cursor":null}}

### GET /v1/companies

Find companies by name, industry, size, location or the vendors they use. Comma-separated values match any of them.
Credits: 1 credit per company returned.
MCP tool: search_companies
CLI: firmographic search --country US --employees 201-500
- q (query): Part of the company name, up to 100 characters.
- industry (query): Comma-separated LinkedIn industries.
- employees (query): Comma-separated employee bands.
- country (query): Comma-separated ISO country codes.
- region (query): Comma-separated regions.
- tech (query): Comma-separated vendor slugs the company uses.
- limit (query): Records to return, 1 to 100. Default 20.
- cursor (query): next_cursor from the last response.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"city":"Austin","country":"US","employees":"51-200","industry":"Software Development","name":"Keystone Labs","region":"North America","source":"sample","updated_at":"2026-11-03T13:42:55.83Z","domain":"keystone.example"}],"meta":{"records":1,"credits_used":1,"credits_left":97,"next_cursor":"keystone.example"}}

### GET /v1/companies/{domain}/tech

The vendors a company uses, with start dates and sources. One charge covers the whole list; an empty list is free.
Credits: 1 credit per company with results.
MCP tool: get_tech_stack
CLI: firmographic tech northwind.example
- domain (path, required): The company's domain.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"category":"customer relationship management","domain":"northwind.example","source":"dns record","started_at":"2025-10-02T13:42:55.83Z","vendor":"Quartz CRM","vendor_slug":"quartz-crm"}],"meta":{"records":1,"credits_used":1,"credits_left":97,"next_cursor":null}}

### GET /v1/vendors

The vendors we track, with the slugs the other routes take.
Credits: Free.
MCP tool: list_vendors
CLI: firmographic vendors
- category (query): Filter by category.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"category":"live chat","market":"SMB","name":"Acme Chat","slug":"acme-chat"}],"meta":{"records":1,"credits_used":0,"credits_left":97,"next_cursor":null}}

### GET /v1/vendors/{vendor}/customers

Companies that use a vendor, with when they started and how we know.
Credits: 1 credit per company returned.
MCP tool: get_vendor_customers
CLI: firmographic customers quartz-crm
- vendor (path, required): The vendor's slug, from /v1/vendors.
- limit (query): Records to return, 1 to 100. Default 20.
- cursor (query): next_cursor from the last response.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"city":"Chicago","country":"US","employees":"201-500","industry":"Transportation and Logistics","name":"Northwind Freight","region":"North America","source":"dns record","updated_at":"2026-11-04T13:42:55.83Z","domain":"northwind.example","started_at":"2025-10-02T13:42:55.83Z"}],"meta":{"records":1,"credits_used":1,"credits_left":96,"next_cursor":null}}

### GET /v1/signals

Company events, newest first: funding, hiring, vendor changes, new technology, and visits to your own website. Each has a source and a date.
Credits: 2 credits per signal returned.
MCP tool: get_signals
CLI: firmographic signals --type funding,hiring --since 7d
- type (query): Comma-separated: funding, hiring, vendor_change, tech, visit.
- domain (query): Only this company.
- industry (query): Comma-separated LinkedIn industries.
- employees (query): Comma-separated employee bands.
- country (query): Comma-separated ISO country codes.
- since (query): How far back: 7d, or a date such as 2026-10-30.
- limit (query): Records to return, 1 to 100. Default 20.
- cursor (query): next_cursor from the last response.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"company":{"name":"Northwind Freight","employees":"201-500","industry":"Transportation and Logistics","country":"US"},"date":"2026-11-03T13:42:55.83Z","domain":"northwind.example","source":"press release","title":"Raised a Series B","type":"funding"}],"meta":{"records":1,"credits_used":2,"credits_left":92,"next_cursor":null}}

### GET /v1/companies/{domain}/jobs

A company's open jobs, newest first.
Credits: 1 credit per job returned.
MCP tool: get_jobs
CLI: firmographic jobs northwind.example
- domain (path, required): The company's domain.
- team (query): Comma-separated teams.
- limit (query): Records to return, 1 to 100. Default 20.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"domain":"northwind.example","location":"Chicago, US","posted_at":"2026-11-04T13:42:55.83Z","source":"careers page","team":"sales","title":"Account Executive"}],"meta":{"records":1,"credits_used":1,"credits_left":91,"next_cursor":null}}

### GET /v1/companies/{domain}/people

A company's decision makers, most senior first.
Credits: 2 credits per person returned.
MCP tool: get_people
CLI: firmographic people northwind.example --seniority vp
- domain (path, required): The company's domain.
- seniority (query): Comma-separated: c_level, vp, head, director, manager.
- department (query): Comma-separated: sales, marketing, engineering, finance, operations, it, support, product.
- limit (query): Records to return, 1 to 100. Default 20.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"department":"sales","domain":"northwind.example","name":"Dana Whitfield","rank":1,"seniority":"vp","source":"sample","title":"VP Sales","updated_at":"2026-11-02T13:42:55.83Z"}],"meta":{"records":1,"credits_used":2,"credits_left":89,"next_cursor":null}}

### GET /v1/leads

The best accounts to contact now: companies with recent signals ranked hot, warm or cold, with the reasons and a contact.
Credits: 1 credit per lead returned.
MCP tool: get_leads
CLI: firmographic leads --heat hot
- heat (query): Comma-separated: hot, warm, cold.
- limit (query): Records to return, 1 to 100. Default 20.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"domain":"northwind.example","company":"Northwind Freight","lead":{"score":60,"heat":"hot","reasons":["funding","hiring"]},"contact":{"department":"sales","domain":"northwind.example","name":"Dana Whitfield","rank":1,"seniority":"vp","source":"sample","title":"VP Sales","updated_at":"2026-11-02T13:42:55.83Z"}}],"meta":{"records":1,"credits_used":1,"credits_left":88,"next_cursor":null}}

### GET /v1/visitors

Companies on your website, grouped by company with the pages they read. Only your workspace's visits are returned.
Credits: Free.
MCP tool: get_visitors
CLI: firmographic visitors --since 30d
- since (query): How far back: 7d by default, or a date such as 2026-10-30.
- limit (query): Records to return, 1 to 100. Default 20.
- fields (query): Comma-separated fields to keep, to make the response smaller.

Example response:
{"data":[{"domain":"keystone.example","company":"Keystone Labs","visits":4,"pages":["/pricing"],"last_seen":"2026-11-05T09:12:44Z"}],"meta":{"records":1,"credits_used":0,"credits_left":88,"next_cursor":null}}

### GET /v1/usage

Credits left in this workspace and the rate for each operation.
Credits: Free.
CLI: firmographic usage

Example response:
{"data":{"credits_left":88,"rates":{"company":1,"search":1,"tech":1,"customers":1,"signals":2,"jobs":1,"people":2,"leads":1,"funding":0,"visitors":0,"vendors":0}}}

### GET /v1/funding/events

Funding rounds with every source, newest announcement first, 100 to a page. For workspaces that have bought credits.
Credits: Free.
MCP tool: get_funding_events
CLI: firmographic funding --period 7d
- period (query): Found in the last 24h, 7d and so on, up to 90d.
- since (query): Found since this timestamp. Use after a missed webhook.
- from (query): Announced on or after this date.
- to (query): Announced on or before this date.
- page (query): The page, from 1.

Example response:
{"data":[{"event":"funding.announced","event_id":"fnd_8f3a","company":"Northwind Freight","domain":"northwind.example","round":"series_b","kind":"venture","amount":{"value":40000000,"currency":"USD","text":"$40M"},"investors":["Example Ventures"],"confidence":0.93,"sources":[{"site":"techcrunch.com","title":"Northwind Freight raises $40M","url":"https://techcrunch.com/example"}],"announced_at":"2026-11-03T00:00:00.000Z","date_source":"url","detected_at":"2026-11-03T13:42:55.830Z"}],"meta":{"records":1,"credits_used":0,"credits_left":92,"next_cursor":null}}

### PUT /v1/funding/subscription

Sends each new funding event to your webhook, one copy each. Past events are not sent. For workspaces that have bought credits. GET reads the subscription and DELETE ends it.
Credits: Free.

Example response:
{"data":{"subscribed":true,"subscribed_at":"2026-11-06T10:00:00.000Z"}}

### POST /v1/webhooks

Send new signals to a public URL, signed. The secret is returned once, here and nowhere else.
Credits: Free.
MCP tool: watch_company
CLI: firmographic watch https://hooks.example.com/firmographic --domains northwind.example --types hiring,vendor_change
- url (body, required): Public http(s) URL that receives each event.
- domains (body): Array of companies to watch. Empty watches all.
- types (body): Array of signal types. Empty sends all. Funding needs a funding subscription.

Example response:
{"data":{"id":"690c9f1e5b1d3a2f7c8e4a10","url":"https://hooks.example.com/firmographic","types":["hiring","vendor_change"],"domains":["northwind.example"],"secret":"whsec_..."}}

### GET /v1/webhooks

This workspace's webhooks. Secrets are never listed.
Credits: Free.

Example response:
{"data":[{"url":"https://hooks.example.com/firmographic","types":["hiring","vendor_change"],"domains":["northwind.example"],"created_at":"2026-11-06T10:00:00.000Z","id":"690c9f1e5b1d3a2f7c8e4a10"}]}

### DELETE /v1/webhooks/{id}

Stops a webhook.
Credits: Free.
- id (path, required): The webhook's id.

Example response:
{"data":{"deleted":true}}

## Public routes

- GET /v.js: The website tracker script.
- POST /v1/collect: Where the tracker reports a page view: {site, path}. It always answers 204. The IP is matched to a company and never stored.
- GET /health: Answers ok when the API is up.

## Errors

- 400 invalid_parameter: A parameter is missing or malformed. The fix names it.
- 400 invalid_json: The request body is not valid JSON.
- 401 unauthorized: The API key is missing, invalid or revoked.
- 402 insufficient_credits: The call costs more credits than the workspace has. Nothing was charged.
- 402 payment_required: Funding events are for workspaces that have bought credits. Nothing was charged.
- 404 not_found: No data for this company or webhook. Nothing was charged.
- 429 rate_limited: Too many requests from this workspace this minute.
- 500 internal: Something failed on our side. Nothing was charged.

## Webhooks

Each event is a POST with the header x-firmographic-signature: sha256=<hmac of the body>, an HMAC-SHA256 of the raw body keyed with the webhook's secret.
A receiver that was down gets what it missed, in order, once it answers 2xx again.
Example event:
{"event":"signal.hiring","data":{"company":{"name":"Northwind Freight","employees":"201-500","industry":"Transportation and Logistics","country":"US"},"date":"2026-11-03T13:42:55.83Z","domain":"northwind.example","source":"careers page","title":"6 open sales roles","type":"hiring","id":"690c9f1e5b1d3a2f7c8e4a11"}}

## CLI

Set FIRMOGRAPHIC_API_KEY. FIRMOGRAPHIC_API_URL overrides the default API address. Any flag becomes a query parameter.
- firmographic company northwind.example
- firmographic search --country US --employees 201-500
- firmographic tech northwind.example
- firmographic vendors
- firmographic customers quartz-crm
- firmographic signals --type funding,hiring --since 7d
- firmographic jobs northwind.example
- firmographic people northwind.example --seniority vp
- firmographic leads --heat hot
- firmographic visitors --since 30d
- firmographic usage
- firmographic funding --period 7d
- firmographic watch https://hooks.example.com/firmographic --domains northwind.example --types hiring,vendor_change