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

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 — 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 or an organization's confirmed-used tech stack

• People — 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 — 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 — 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

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

• Technology find — 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 — resolve a list of project names or slugs to canonical identifiers

• Job function & level lookup — resolve a list of job titles to canonical job function and level identifiers

Intelligence endpoints

AI-generated intelligence on the organizations you care about.

• Signals — search recent account signals by organization, person, technology, job function, account list or signal ID; search Priority Signals by organization, person, or job post IDs, or source signal ID.

• Intelligence briefs — generate an AI account brief for an organization

Lists

Create, manage, and access your saved lists.

• Organization lists — create, manage, and access saved organization lists

• Contact lists — create, manage, and access saved people lists

Support

Report data quality issues and submit general support requests programmatically.

• Support — report a data quality issue (POST /support/data-quality) or submit a general support request (POST /support); both are free and reply to your account email

MCP

• MCP — connect Sumble to Claude, Cursor, ChatGPT, and other MCP clients

Getting started

1. Generate your API key

Go to 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/v9/

This is the only base URL for the Sumble API. If you have seen a sumble.com/paid-api/... path in an older example or a support thread, replace it with https://api.sumble.com/ — that path is not a supported public endpoint.

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:

curl https://api.sumble.com/v9/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). Each endpoint page documents its full set of inputs and selectable fields.

Next steps

• Browse the endpoint reference for inputs, response fields, and examples

• Prefer to work through an AI client? Set up MCP

• Review credit costs before running large jobs

File downloads

Most endpoints that return rows accept a file_name parameter. Set it and the response carries file metadata and an authenticated Sumble download URL in place of the inline rows, at the same credit cost. Opening the download URL requires the file owner's Sumble web session.

End the name in .csv, .xlsx or .json. All three hold the same results. They differ in how those results are shaped and typed:

• .csv is plain UTF-8 text, so every cell is text. A value starting with =, +, - or @ gets a leading apostrophe, which stops a spreadsheet running it as a formula.

• .xlsx is an Excel workbook with a single sheet, named for what it holds. Numbers stay numeric and booleans stay boolean, so sorting and arithmetic work without retyping a column, and text that looks like a formula keeps its exact characters. Excel caps a cell at 32,767 characters and longer values are truncated.

• .json is an array of objects, indented and UTF-8, holding the same results the response would have returned inline. Nothing is quoted, truncated or flattened to suit a spreadsheet, so this is the format to take when the results are going into a program.

The column names are on row 1 of an .xlsx, frozen and filterable, so a library's default header row reads them: pandas.read_excel(path) needs no offset. The Sumble surface the file came from, who asked for it and when are in the workbook's document properties (File > Info in Excel) and its printed footer. Files made before this changed had a title row above the column names; read those with pandas.read_excel(path, header=1).

An .xlsx folds each Sumble link into the name it belongs to. Where a .csv has a sumble_url column beside name, the workbook makes the name itself a link and drops the URL column. The same goes for a prefixed pair, such as organization_name with organization_sumble_url. Excel shows the link, but a library that reads cell values does not: pandas.read_excel gives you the name without the URL. Take the .csv or the .json, or the inline rows, when you need the URL as data. The columns list in the response metadata always describes what that file actually holds.

A .csv and an .xlsx are flat; a .json is not. A sheet has one row per result and no nested columns, so the two spreadsheet formats open an object out into prefixed columns — a job's organization becomes organization_id, organization_name, organization_domain — and write a repeated value, such as a person's experience or a job's technologies, as compact JSON text in a single cell. A .json keeps the structure the inline response has, so organization is an object and technologies is an array. If you are parsing those cells back out, take the .json instead.

Two consequences for the response metadata. columns on a .json lists the top-level keys of each object, not the sheet's column names, and row_count counts the top-level results — for the tech stack, that is the business functions, where the sheet has one row per evidence technology.

Credits

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

Endpoint	Cost
Organizations	Per organization: 1 base credit + 1 per paid attribute + the metrics requested per entity. Unmatched inputs are free.
Organization signals	1 credit per signal returned. Organizations with no returned signals are free.
Organization tech stack	1 credit per technology returned. Organizations with no confirmed-used technologies are free.
Signals search	1 credit per signal returned. Searches with no returned signals are free.
Priority Signals search	1 credit per priority signal returned. Searches with no returned priority signals are free.
Intelligence briefs	50 credits per completed brief
People	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.
Job posts	Per job: 1 base credit + 1 per paid attribute + 1 per related person returned. Unmatched inputs are free.
Teams	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	1 credit per 100 matched titles
Organization lists	1 credit per list or organization returned
Create / add to list	No credit cost
Contact lists	1 credit per list or person returned
Create / add to contact list	No credit cost
Technologies find	1 credit if results found
Technologies lookup	1 credit per 100 matched technologies
Technology categories lookup	1 credit per 100 matched categories
Projects lookup	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 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.

Timeouts

A request can run for up to 55 seconds. After that the API stops it and responds with status code 504 and this body:

{
  "detail": "The request took longer than 55 seconds and was stopped. No credits were charged. Retry it, or send fewer items per request.",
  "type": "request_timeout"
}

A request that times out is not charged. Set your client timeout to 65 seconds or more. A client that disconnects earlier is still charged if the request completes.

If a request times out, retry it. If it keeps timing out, send fewer items per request, for example fewer organizations or fewer entities per call.

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
504	Timed out, no credits charged. Retry