> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/api.md).

# Overview

The Sumble API is a RESTful service for programmatic access to Sumble's organization, people, and job-post data. Use it to enrich CRM data, build lead-generation tools, and run market research queries.

## Overview

The API is organized into a few groups of endpoints:

#### [Core data](/api/core-data.md)

Sumble's primary entities. Each is a single composable endpoint: resolve a list you already have, or search by an advanced filter, then use `select` to choose exactly which attributes and metrics come back.

* [Organizations](/api/core-data/organizations.md) — resolve a list of companies or search by technology, job function, industry, and firmographic filters; compose which attributes and per-entity metrics return; retrieve recent organization signals
* [People](/api/core-data/people.md) — resolve a list of people or search by organization and role; compose which attributes return, including contact information (email, phone) and related people (managers, direct reports)
* [Job posts](/api/core-data/jobs.md) — resolve a list of jobs or search by organization and filters; compose which attributes return, including full descriptions, extracted technologies, teams, and functions, and related people (hiring managers, team members)
* [Teams](/api/core-data/teams.md) — resolve a list of teams or search by organization and filters; compose which attributes return, including ICP fit score, related people, and the team's job posts

#### [ID & slug lookups](/api/lookups.md)

Turn human-readable names into the canonical slugs and identifiers the core data endpoints expect in their filters.

* [Technology find](/api/lookups/technologies.md) — search the catalog for technology names and slugs, resolve known names/slugs/aliases to canonical technologies, and resolve technology categories to their constituent technologies
* [Project find](/api/lookups/projects.md) — resolve a list of project names or slugs to canonical identifiers
* [Job function & level lookup](/api/lookups/job-title-lookup.md) — resolve a list of job titles to canonical job function and level identifiers

#### [Intelligence endpoints](/api/intelligence.md)

AI-generated intelligence on the organizations you care about.

* [Intelligence briefs](/api/intelligence/intelligence-briefs.md) — generate an AI account brief for an organization

#### [Lists](/api/lists.md)

Create, manage, and access your saved lists.

* [Organization lists](/api/lists/organization-lists.md) — create, manage, and access saved organization lists
* [Contact lists](/api/lists/contact-lists.md) — create, manage, and access saved people lists

#### [MCP](/api/mcp.md)

* [MCP](/api/mcp.md) — connect Sumble to Claude, Cursor, ChatGPT, and other MCP clients

## Getting started

### 1. Generate your API key

Go to [sumble.com/account/api-keys](https://sumble.com/account/api-keys) and create a new key. Store it securely — it won't be shown again.

### 2. Base URL

All endpoints are served from:

```
https://api.sumble.com/v6/
```

### 3. Authenticate

Every request requires your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

### 4. Make your first request

This request resolves an organization by domain and composes exactly the fields it returns — baseline attributes plus a per-technology metric:

```bash
curl https://api.sumble.com/v6/organizations \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "organizations": [
      { "url": "stripe.com" }
    ],
    "select": {
      "attributes": ["name", "industry", "employee_count"],
      "entities": [
        { "type": "technology", "term": "python", "metrics": ["job_post_count"] }
      ]
    }
  }'
```

### 5. Compose your response

Most endpoints follow the same pattern: provide either a **list** of entities to resolve or a **filter** to search, then use the `select` block to request exactly the `attributes` — and, where supported, per-entity `entities` metrics — you want back. You only pay for what you request (see [Credits](#credits)). Each endpoint page documents its full set of inputs and selectable fields.

### Next steps

* Browse the [endpoint reference](#overview) for inputs, response fields, and examples
* Prefer to work through an AI client? Set up [MCP](/api/mcp.md)
* Review [credit costs](#credits) before running large jobs

## Credits

API calls consume credits from your account. Costs vary by endpoint:

| Endpoint                                                                                   | Cost                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Organizations](/api/core-data/organizations.md)                                           | Per organization: 1 base credit + 1 per paid attribute + the metrics requested per entity. Unmatched inputs are free.                                                                                                                                          |
| [Organization signals](/api/core-data/organizations.md#organization-signals)               | 1 credit per signal returned. Organizations with no returned signals are free.                                                                                                                                                                                 |
| [Intelligence briefs](/api/intelligence/intelligence-briefs.md)                            | 50 credits per completed brief                                                                                                                                                                                                                                 |
| [People](/api/core-data/people.md)                                                         | Per person: 1 base credit + 1 per paid attribute + 1 per related person returned. Unmatched inputs are free. Contact reveals cost extra (10 credits per email, 80 per phone, first reveal only) — see the [People page](/api/core-data/people.md#credit-cost). |
| [Job posts](/api/core-data/jobs.md)                                                        | Per job: 1 base credit + 1 per paid attribute + 1 per related person returned. Unmatched inputs are free.                                                                                                                                                      |
| [Teams](/api/core-data/teams.md)                                                           | Per team: 1 base credit + 1 per paid attribute + 1 per related person + 1 per job post returned. Unmatched inputs are free.                                                                                                                                    |
| [Job function & level lookup](/api/lookups/job-title-lookup.md)                            | 1 credit per 100 matched titles                                                                                                                                                                                                                                |
| [Organization lists](/api/lists/organization-lists.md)                                     | 1 credit per list or organization returned                                                                                                                                                                                                                     |
| [Create / add to list](/api/lists/organization-lists.md)                                   | No credit cost                                                                                                                                                                                                                                                 |
| [Contact lists](/api/lists/contact-lists.md)                                               | 1 credit per list or person returned                                                                                                                                                                                                                           |
| [Create / add to contact list](/api/lists/contact-lists.md)                                | No credit cost                                                                                                                                                                                                                                                 |
| Technologies find                                                                          | 1 credit if results found                                                                                                                                                                                                                                      |
| [Technologies lookup](/api/lookups/technologies.md#look-up-technologies)                   | 1 credit per 100 matched technologies                                                                                                                                                                                                                          |
| [Technology categories lookup](/api/lookups/technologies.md#look-up-technology-categories) | 1 credit per 100 matched categories                                                                                                                                                                                                                            |
| [Projects lookup](/api/lookups/projects.md#look-up-projects)                               | 1 credit per 100 matched projects                                                                                                                                                                                                                              |

A `technology_category` entity with `granularity: "exploded"` counts each technology in the category individually — a category with 3 technologies multiplies that entity's metric cost by 3.

See [Credits](/web-app/exports-credits/credits-and-exports.md) for details on monthly allocations and purchasing additional credits.

## Rate limits

API usage is subject to rate limiting to ensure service stability. Each user can do 10 requests per second (aggregated through all the endpoints), allowing occasional bursts.

Once the rate limit is reached, the API responds with response code 429.

## Error responses

| Status Code | Meaning                                   |
| ----------- | ----------------------------------------- |
| 200         | Success                                   |
| 202         | Accepted, in progress — retry soon        |
| 400         | Bad request — check your request body     |
| 401         | Unauthorized — invalid or missing API key |
| 402         | Insufficient credits                      |
| 429         | Rate limited — wait and retry             |
| 500         | Server error — contact support            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sumble.com/api/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.