# API

Programmatic access to Sumble's organization, people, job postings, and organization list data.

### Overview

The Sumble API is a RESTful service for enriching CRM data, building lead generation tools, and running market research queries. It exposes six endpoint groups:

* **Organizations find** — search companies by technology, job function, industry, and firmographic filters
* **Organizations enrich** — check which technologies appear at a given company
* **Organizations match** — match a list of companies by name, URL, or location against Sumble's database
* **People find** — find people at an organization by role and seniority
* **People find-related-people** — find related people at the same organization based on shared attributes
* **People enrich** — get contact information (email, phone) for a person
* **Jobs find** — get structured job postings with extracted technologies, teams, and functions
* **Jobs find-related-people** — find hiring managers and team members related to a job listing
* **Organization lists** — create, manage, and access saved organization lists
* **Contact lists** — create, manage, and access saved people lists
* **Technologies find** — look up technology names and slugs for use in other endpoints

### 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. Make your first request

All API requests require the key as a Bearer token in the Authorization header:

```bash
curl https://api.sumble.com/v5/organizations/enrich \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "organization": {
      "domain": "stripe.com"
    },
    "filters": {
      "technologies": ["python"]
    }
  }'
```

### Credits

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

| Endpoint                                                                  | Cost                                                                        |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Organizations find](https://docs.sumble.com/api/organizations)           | 5 credits per row, or 5 per filter term per row with entity details (min 5) |
| [Organizations enrich](https://docs.sumble.com/api/organizations)         | 5 credits per technology found                                              |
| [Organizations match](https://docs.sumble.com/api/organizations)          | 1 credit per matched organization                                           |
| [People find](https://docs.sumble.com/api/people)                         | 1 credit per person returned                                                |
| [People find-related-people](https://docs.sumble.com/api/people)          | 1 credit per person returned                                                |
| [People enrich](https://docs.sumble.com/people#enrich-person)             | 10 credits per successful enrichment (free if cached or not found)          |
| [Jobs find](https://docs.sumble.com/api/jobs)                             | 2 credits per job, or 3 with descriptions                                   |
| [Job details](https://docs.sumble.com/api/jobs)                           | 1 credit per job                                                            |
| [Jobs find-related-people](https://docs.sumble.com/api/jobs)              | 1 credit per person returned                                                |
| [Organization lists](https://docs.sumble.com/api/organization-lists)      | 1 credit per list or organization returned                                  |
| [Create / add to list](https://docs.sumble.com/api/organization-lists)    | No credit cost                                                              |
| [Contact lists](https://docs.sumble.com/api/contact-lists)                | 1 credit per list or person returned                                        |
| [Create / add to contact list](https://docs.sumble.com/api/contact-lists) | No credit cost                                                              |
| Technologies find                                                         | 1 credit if results found                                                   |

Technology categories count each technology in the category individually. A category with 3 technologies costs 15 credits per row on the organizations/find endpoint.

See [Credits](https://docs.sumble.com/web-application/credits-and-exports) 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                                   |
| 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            |

### Base URL

All endpoints are served from:

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

### Endpoints

* [Organizations](https://docs.sumble.com/api/organizations) — search and enrich company data
* [Jobs](https://docs.sumble.com/api/jobs) — find job postings by organization and filters
* [People](https://docs.sumble.com/api/people) — find professionals by organization and role
* [Organization lists](https://docs.sumble.com/api/organization-lists) — access saved organization lists and the organizations in them
* [Contact lists](https://docs.sumble.com/api/contact-lists) — create and manage saved people lists