---
title: "Incumbently API docs: endpoints, MCP, credits and errors"
description: "The Incumbently API: companies using any tool, who started or stopped, company stacks and decision makers. Endpoints with examples, MCP for Claude, ChatGPT and Cursor, credits, limits and errors."
url: https://www.incumbently.com/docs
---

# Incumbently API

Which companies use a tool, who started or stopped, a company's full stack, and who to contact there. JSON over HTTPS, one Bearer key, priced per record.

## Quickstart

1. **Get a key.** On Pro or Max, open Claude and API in the app and create a key. It starts with inc_live_.
2. **Send it as a Bearer token.** Every request carries Authorization: Bearer <key>. There's nothing else to set up.
3. **Call an endpoint.** Start with /v1/me to check your plan and credits. It's free.

```bash
curl "https://app.incumbently.com/v1/me" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

## Basics

| Topic | Details |
| --- | --- |
| **Base URL** | https://app.incumbently.com/v1 |
| **Auth** | Authorization: Bearer inc_live_… (an API key), or an OAuth access token from the MCP sign-in. |
| **Format** | JSON responses. Lists come back as { data, meta, credits }. |
| **Credits** | One credit per record returned. /me, /tools and contact lists are free. A work email is 1 credit, only when found. |
| **Limits** | 60 requests a minute per key. Pages hold up to 100 records. |
| **Plans** | The API comes with Pro (1,000 credits a month) and Max (5,000). |

## Endpoints

| Endpoint | What it returns | Credits |
| --- | --- | --- |
| `GET /me` | Your plan and credits | Free |
| `GET /tools` | Search tools | Free |
| `GET /tools/{tool}` | Tool summary | 1 credit |
| `GET /tools/{tool}/companies` | Companies using a tool | 1 credit per company |
| `GET /tools/{tool}/changes` | Who started or stopped | 1 credit per change |
| `GET /companies/{domain}` | Company stack | 1 credit |
| `GET /companies/{domain}/contacts` | Decision makers | Free |
| `GET /contacts/{id}/email` | Work email | 1 credit, if found |

### Your plan and credits

`GET https://app.incumbently.com/v1/me` · Credits: Free

The workspace the key belongs to, its plan, and the credits left this month.

```bash
curl "https://app.incumbently.com/v1/me" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": {
    "workspace": "Northwind",
    "plan": "pro",
    "credits": {
      "monthly": 1000, "used_this_month": 212, "extra": 0, "remaining": 788,
      "resets_at": "2026-12-01T00:00:00.000Z"
    }
  }
}
```

### Search tools

`GET https://app.incumbently.com/v1/tools` · Credits: Free

Find a tool in the catalogue of 1,800 and get its id for the other calls. Exact name matches come first, then the most-used tools.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `search` | query | string | Tool name or category, like zendesk or email marketing. |

```bash
curl "https://app.incumbently.com/v1/tools?search=zendesk" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "zendesk", "name": "Zendesk", "category": "digital customer service",
      "group": "Customer Experience & Support", "website": "zendesk.com", "companies": 24121
    }
  ]
}
```

### Tool summary

`GET https://app.incumbently.com/v1/tools/{tool}` · Credits: 1 credit

How many companies use a tool today, how many started and stopped in the last 30 days, and 12 months of monthly changes.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `tool` (required) | path | string | Tool id from /v1/tools, like zendesk. A tool's name works too. |

```bash
curl "https://app.incumbently.com/v1/tools/zendesk" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": {
    "id": "zendesk",
    "name": "Zendesk",
    "category": "digital customer service",
    "companies": 24121,
    "adopted_30d": 341,
    "dropped_30d": 452,
    "drops_tracked": true,
    "monthly_changes": [{ "month": "2026-10", "count": 779 }]
  },
  "credits": { "charged": 1, "remaining": 787 }
}
```

### Companies using a tool

`GET https://app.incumbently.com/v1/tools/{tool}/companies` · Credits: 1 credit per company

Every company that uses a tool today, with industry, size, country and the date we first saw it there.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `tool` (required) | path | string | Tool id from /v1/tools, like zendesk. A tool's name works too. |
| `country` | query | string | Two-letter country code, like US or DE. |
| `size` | query | string | Company size band, like 51-200. |
| `industry` | query | string | Industry, like Software Development. |
| `page` | query | integer | Page number. Default 1. |
| `per_page` | query | integer | Records per page, 1 to 100. Default 25. |

```bash
curl "https://app.incumbently.com/v1/tools/zendesk/companies?country=US&size=51-200&per_page=2" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": [
    {
      "domain": "northwind.io", "name": "Northwind", "industry": "Software Development",
      "size": "51-200", "country": "US", "region": "North America", "using_since": "2024-03-11"
    },
    {
      "domain": "bluefin.health", "name": "Bluefin Health", "industry": "Hospitals and Health Care",
      "size": "51-200", "country": "US", "region": "North America", "using_since": "2025-01-20"
    }
  ],
  "meta": { "page": 1, "per_page": 2, "total": 3184, "pages": 1592 },
  "credits": { "charged": 2, "remaining": 785 }
}
```

### Who started or stopped

`GET https://app.incumbently.com/v1/tools/{tool}/changes` · Credits: 1 credit per change

Companies that adopted or dropped a tool, newest first. Defaults to the last 30 days. How far back you can go follows your plan: 12 months on Pro, all of it on Max.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `tool` (required) | path | string | Tool id from /v1/tools, like zendesk. A tool's name works too. |
| `kind` | query | string | adopted or dropped. Leave it out for both. |
| `since` | query | date | Earliest date, like 2026-10-01. Default 30 days ago. |
| `size` | query | string | Company size band, like 51-200. |
| `country` | query | string | Two-letter country code, like US or DE. |
| `page` | query | integer | Page number. Default 1. |
| `per_page` | query | integer | Records per page, 1 to 100. Default 25. |

```bash
curl "https://app.incumbently.com/v1/tools/zendesk/changes?kind=dropped&since=2026-10-01" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "c_8f2a91", "domain": "arbor-logistics.com", "name": "Arbor Logistics", "change": "dropped",
      "at": "2026-11-04", "industry": "Transportation", "size": "201-500", "country": "US"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 452, "pages": 19, "since": "2026-10-01" },
  "credits": { "charged": 25, "remaining": 760 }
}
```

### Company stack

`GET https://app.incumbently.com/v1/companies/{domain}` · Credits: 1 credit

Every tool we see a company running, grouped by category, plus each tool it added or dropped and when.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `domain` (required) | path | string | Company website, like stripe.com. |

```bash
curl "https://app.incumbently.com/v1/companies/northwind.io" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": {
    "domain": "northwind.io",
    "name": "Northwind",
    "industry": "Software Development",
    "size": "51-200",
    "country": "US",
    "stack": [
      {
        "category": "Customer Experience & Support",
        "tools": [{ "name": "Intercom", "category": "digital customer service" }]
      }
    ],
    "changes": [
      { "at": "2026-11-02", "change": "dropped", "tool": "Zendesk", "description": "Stopped using Zendesk" }
    ]
  },
  "credits": { "charged": 1, "remaining": 759 }
}
```

### Decision makers

`GET https://app.incumbently.com/v1/companies/{domain}/contacts` · Credits: Free

Senior people at a company (C-suite, VP, head, director) with title, team and LinkedIn. Ask for one team to narrow it down. Emails you've already unlocked come back filled in.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `domain` (required) | path | string | Company website, like stripe.com. |
| `team` | query | string | Only one team: Information Technology, Engineering, Sales & Business Development, Advertising & Marketing, Customer/Client Service, Finance & Accounting, Human Resources or Operations. |
| `limit` | query | integer | How many people, 1 to 25. Default 10. |

```bash
curl "https://app.incumbently.com/v1/companies/northwind.io/contacts?team=Customer/Client%20Service&limit=1" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "per_k2Qx81", "name": "Maya Okafor", "title": "VP of Customer Success", "level": "vp",
      "team": "Customer/Client Service", "linkedin_url": "https://www.linkedin.com/in/example",
      "has_email": true, "email": null
    }
  ],
  "meta": { "domain": "northwind.io", "total": 18 }
}
```

### Work email

`GET https://app.incumbently.com/v1/contacts/{id}/email` · Credits: 1 credit, if found

One contact's work email and whether it's verified. Charged only when we find one, and free every time after that.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` (required) | path | string | Contact id from /companies/{domain}/contacts. |

```bash
curl "https://app.incumbently.com/v1/contacts/per_k2Qx81/email" \
  -H "Authorization: Bearer $INCUMBENTLY_KEY"
```

Response:

```json
{
  "data": { "id": "per_k2Qx81", "email": "maya@northwind.io", "status": "verified" },
  "credits": { "charged": 1, "remaining": 758 }
}
```

## Pagination and credits

List endpoints take `page` and `per_page` (up to 100) and return `meta` with `total` and `pages`. Every charged response carries `X-Credits-Charged` and `X-Credits-Remaining` headers and a `credits` object. You're never charged for more records than you have credits for.

## Errors

Errors return `{"error": {"code": "…", "message": "…"}}`.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad_request` | A parameter has the wrong format, like a date that isn't YYYY-MM-DD. |
| 401 | `unauthorized` | The key is missing, wrong or revoked. |
| 402 | `insufficient_credits` | This month's credits are used up. They renew on the 1st. |
| 403 | `plan_required` | The API comes with Pro and Max. |
| 404 | `not_found` | No tool, endpoint or email by that name. |
| 429 | `rate_limited` | More than 60 requests a minute on one key. Wait for Retry-After. |
| 503 | `unavailable` | Data is briefly unavailable. Try again in a minute. Nothing is charged. |

## MCP: Claude, ChatGPT and Cursor

Server address: `https://app.incumbently.com/mcp` (remote, Streamable HTTP, OAuth). Pro and Max.

**Claude**

1. Open Settings, then Connectors.
2. Add a custom connector and paste the address.
3. Sign in to Incumbently and allow access.

**ChatGPT**

1. Open Settings, then Apps and Connectors.
2. Create a connector with the address.
3. Sign in to Incumbently and allow access.

**Cursor**

1. Add the server to .cursor/mcp.json.
2. Reload Cursor and sign in when asked.

```json
{
  "mcpServers": {
    "incumbently": {
      "url": "https://app.incumbently.com/mcp"
    }
  }
}
```

| Tool | What it does |
| --- | --- |
| `search_tools` | Find a tool and its id. |
| `tool_summary` | Companies using a tool, plus 30-day adoptions and drops. |
| `companies_using` | Companies that use a tool, filtered by country, size or industry. |
| `tool_changes` | Who adopted or dropped a tool, and when. |
| `company_stack` | A company's stack and change history. |
| `find_contacts` | Decision makers at a company, by team. |
| `get_contact_email` | One contact's work email. 1 credit, only when found. |
| `my_tracked_tools` | The tools your workspace tracks, with their numbers. |

Questions are unlimited under fair use. Answers follow your plan's history. Remove an app in the dashboard and it loses access at once.

## Alerts and webhooks

| Plan | Alerts |
| --- | --- |
| Free | No email alerts. The monthly report is in the dashboard. |
| Pro | A daily email digest of new changes across your tools. |
| Max | Real-time email, plus a post to Slack or any webhook URL. |

Webhooks get a JSON POST. A Slack incoming-webhook URL works as is, because Slack shows the `text` field.

```json
{
  "text": "Incumbently: 2 new changes\nDropped Zendesk: Arbor Logistics (arbor-logistics.com)\nAdopted Intercom: Arbor Logistics (arbor-logistics.com)",
  "changes": [
    { "tool": "Zendesk", "company": "Arbor Logistics", "domain": "arbor-logistics.com", "kind": "Dropped", "when": "Nov 6" }
  ]
}
```

## Plans

| Feature | Free | Pro · $149 | Max · $249 |
| --- | --- | --- | --- |
| Tracked tools | 1 | 3 | 10 |
| Data | Monthly report, a month behind | Live | Live |
| Company lookups | 100 a month | Unlimited | Unlimited |
| Customers per tool | First 100 | All | All |
| Change history | One month | 12 months | Full |
| Decision makers | — | Yes | Yes |
| Claude, ChatGPT and Cursor | — | Yes | Yes |
| API credits a month | — | 1,000 | 5,000 |
| CSV export rows a month | — | 2,000 | 10,000 |
| Alerts | — | Daily email | Real-time email and webhook |
| Seats | 1 | 3 | Unlimited |

## For agents

- [openapi.json](https://app.incumbently.com/openapi.json): OpenAPI 3.1 for every endpoint on this page.
- [llms.txt](https://www.incumbently.com/llms.txt): A map of the site for language models.
- [agents.md](https://www.incumbently.com/agents.md): How an AI agent should use Incumbently.
- [docs.md](https://www.incumbently.com/docs.md): This page as Markdown.