People
Find, match, and enrich people
The single endpoint for working with people. Provide either a list of people to resolve (list mode) or a filter to find people using structured criteria or plain-language search, and compose exactly which attributes you get back. This replaces the previous find, find-related-people, and enrich endpoints.
Input
Provide exactly one of:
people— a list of up to 1,000 people to resolve, each identified by a Sumbleperson_id, alinkedin_url, or a workemail(used in that order of precedence). Limited to 25 entries when requesting contact attributes, related people, or email identifiers. Covers the previousenrichandfind-related-peopleflows.Entries identified by
emailmay also carry an optionalname. It isn't an identifier — an entry with only a name is rejected — but it noticeably improves email resolution, especially for addresses likefirstname@company.comwhere the name can't be read off the address, and for people whose email is at a former employer. Include it whenever you have it.
filterselects people using an advanced query or search. Useorganization_ids, up to 1,000, and/or a savedorganization_list_idto scope either approach to those organizations. Covers the previousfindflow.
Advanced query
filter.query matches people using a structured query expression over job functions, technologies, job levels, locations, and more. Provide an organization scope.
In filter mode, limit (default 10, max 200) and offset page through results, and order_by_column sorts by start_date, job_level, or person_score. Sorting by person_score requires exactly one organization in scope and an ICP configured for your account.
Search
Use filter.search to describe responsibilities or experience in plain language. Results are ranked by relevance. Search is available on Sumble Pro and Enterprise plans, and needs API version v8 or later.
For search, requested_total sets the maximum number of people across all pages, from 1 to 1,000. It defaults to limit, so a request with limit: 10 returns at most ten people in total. To request 100 people in pages of 20, set requested_total: 100 and limit: 20 from the first request. Keep the search, scope, and requested_total unchanged when paging, and increase offset by limit.
Results include the best available matches, which may only partly match your description. total is the size of this ranked list, capped by requested_total, rather than a count of everyone who might match. A short or empty page can mean some profiles are unavailable. Continue until offset + limit >= total.
{
"filter": {
"search": "Salesforce administrators or revenue operations managers who own Salesforce CRM",
"organization_ids": [10441, 27730],
"locations": ["US:Texas"]
},
"select": { "attributes": ["name", "job_title"] },
"limit": 25,
"offset": 0
}Omit the organization filters to search across Sumble's people records. With an organization scope, add "include_past_employers": true to filter to include former employees. This option requires search.
Add locations to filter to search only people whose profile location is in one of the places you name. Pass up to 200 location codes from Find locations, such as US, US:Texas, or US:Texas:Austin. A person matches when their location is in any of them, and a state or country code matches every city in it. A code that resolves to no place, or that is not shaped like US, US:Texas or US:Texas:Austin, returns a 400 error naming it. Region codes such as EMEA are not accepted: send the region as parent, then each subregion it returns as parent, and pass the country codes. This option requires search.
search cannot be combined with query. Search results come back in relevance order. Set order_by_column to sort them by start_date, job_level, or person_score instead. A sort covers the search's results up to requested_total, so set requested_total before the first page.
person_score works with search too. Each person gets the same score filter mode gives them, and the results stay in relevance order unless you sort by person_score.
Writing a good search
Describe the people the way their own profile would, in one or two short sentences: the role, what they own or do, and the concrete tools, products, or domains they work with.
What works well:
Short role lists with a few specifics. A plural role noun, a seniority, and a product name work better than a paragraph of instructions.
Naming the seniority, such as "director or VP of finance", and listing the titles a role goes by when they vary, such as "engineering managers, directors of engineering, heads of platform".
Exact product and technology names.
Including the forms people use for a role or field, such as "engineer" and "engineering".
Filters for what must hold.
organization_idsenforces the employer andlocationsenforces the place, using codes from Find locations.Another language when results are thin and the people you want may write their profiles in it, such as "engenheiro de dados com experiência em Spark". Run it as a second search and merge the results by
person_id.
Searches that work well: "FinOps lead who manages cloud cost optimization"; "database administrators or backend engineers who work with PostgreSQL in production"; "CISO, head of operational resilience, or leaders responsible for business continuity and disaster recovery".
What does not work:
Long instruction-style text. Keep the search to the people you want; instructions about what to return or how to format it are not followed.
Composable response
The select block dictates exactly which attributes return — nothing is mandatory:
attributes— a list of person attributes, or"all". Available:name,linkedin_url,job_title,job_function,job_level,location,country,current_employer,technologies,person_score, the profile attributesexperienceandsummary, and the contact attributesemailandphone.person_idandsumble_urlare always included for free.The contact attributes
emailandphonemust be requested explicitly — they are never part of"all"— and are only available in list mode, for up to 25 people per request.The profile attributes must also be requested explicitly. They work in both modes; a list-mode request selecting them is capped at 200 people, matching the search-mode page size.
experienceis the person's LinkedIn-style role history, newest first:title,start_dateandend_date(YYYY-MM, null end for a current role),duration,location, the person's owndescriptionof the role, and anemployershaped likecurrent_employer(organization_id,slug, andsumble_urlwhen Sumble knows the organization, plus the employer'snameandlinkedin_urlfrom the profile).summaryis the profile's "About" section as the person wrote it.person_scoreis your ICP match score (0–100) with its contribution breakdown. See Scores. It requires filter mode with exactly one organization in scope and an ICP configured;"all"includes it opportunistically when those requirements are met. Requesting it explicitly in list mode returns an error, and it isn't available for related people. Sorting byperson_scoreis descending only, and it addsperson_scoreto every returned row, charged like any paid attribute.
related_people— inferred managers and/or direct reports for each matched person. Choose thedirection(managers,direct_reports) and which attributes to return for them. Addconfidenceto a related person's attributes to get why they were returned: a 0–1 score with its breakdown. Available in list mode only, for up to 25 people per request.
File output
Set file_name, such as people.csv, to get the results as a file instead of inline people. The formats and the response shape are in File downloads.
A .json file contains one object per person in the same structure as the inline people results, so the current employer and person score stay objects and technologies, experience, managers, and direct reports stay arrays.
A .csv or .xlsx file contains one row per person. In list mode, unmatched inputs remain as rows with their input_* columns populated. Person, current-employer, and person-score scalar values have their own columns. Repeated or nested values — technologies, experience, matched score features, managers, and direct reports — are compact JSON in one cell.
Pass file_name only when starting an asynchronous request. Poll with request_id alone; the successful poll carries the file.
If the file cannot be written, the request still succeeds and returns the rows inline with no file. A download problem never costs you a result you have already paid for, so handle both shapes.
Credit cost
Charged per matched person (list mode) or per returned person (search mode). Unmatched inputs are free.
Per person the cost is:
1 base credit, plus:
1 credit per paid attribute requested (
nameis free), plus1 credit per related person returned.
Contact and email-identifier charges apply on top:
Email reveal: 10 credits the first time your account reveals an email for a given person; repeat requests while the reveal is active are free, and nothing is charged when no email is found.
Phone reveal: 80 credits the first time your account reveals a phone for a given person, with the same repeat and not-found rules.
Email identifiers: resolving an input
emailto a person costs 20 credits per unique email that resolves; emails that don't resolve are free.
For example, returning 10 people with 2 paid attributes each costs 10 × (1 + 2) = 30 credits. The API checks affordability up front and returns HTTP 402 before doing any work you can't pay for.
Asynchronous requests
POST /people is asynchronous in both modes: it starts a background job and returns immediately with a request_id. You then poll the same endpoint with that request_id to retrieve the status and, once ready, the result.
Start the request
POST /people with a people or filter body exactly as described above. The response has status: "pending" and a request_id. No credits are charged yet, but the request is fully validated and your balance is pre-checked up front, so you still receive the usual 400/402 immediately — for example if person_score is misconfigured or you can't afford the worst-case cost.
Asynchronous list requests also let Sumble fall back to a deeper reverse-enrichment lookup for input emails it can't resolve immediately — those results are filled in before the job completes, rather than coming back unmatched.
Limits on open searches
Each user can have 20 searches pending or running at a time. Starting another one returns HTTP 429 with "type": "search_concurrency" and a Retry-After header giving the seconds to wait. Nothing is started and no credits are charged. Wait that long, then send the same request again. The limit applies only to starting a search, so polls and requests without search are never refused this way.
Poll request body
request_id
string
The request_id returned when the job was started. Provide this alone to poll — don't send people, filter, or file_name with it.
Job status values
status
Meaning
pending
Queued, not started yet.
running
The request is being processed.
succeeded
Done; the result fields are included in the response.
failed
The request did not finish. The error field says why and whether to resubmit.
When you're charged
Credits are charged once, on the first poll that returns succeeded. failed jobs cost nothing. Polling is always free: the credits_used field reflects what this particular call charged, so the successful poll reports the total and every subsequent poll of the same job reports 0.
Async response fields
Alongside the usual result fields, the response includes:
request_id
string
Id of the async job. Poll POST /people with this id to retrieve the result.
status
string
Job status — one of pending, running, succeeded, or failed.
file
object
Metadata and download URL for the file requested with file_name; present when the job succeeds. See File downloads.
Failed requests
A failed poll response carries an error object:
code
string
unavailable, expired, or internal.
message
string
What happened and what to do next.
retry_at
string (ISO 8601)
When to resubmit. Omitted for internal.
If retry_at is set, resubmit the original request at or after that time. If it isn't, the request failed because of an internal error; contact support@sumble.com if it keeps failing.
code
Meaning
unavailable
The service was temporarily unavailable and could not complete the request: it was too busy, or a restart interrupted it. retry_at is about 30 seconds after the failure.
expired
A filter.search request waited more than 30 minutes to start, so it never ran. retry_at is the time it failed, so resubmit now.
internal
Something went wrong on our side. No retry_at.
To resubmit, send the original people or filter request again. That starts a new job with a new request_id. Polling the failed request_id keeps returning the same failure, and retry_at doesn't move. A failed job costs nothing.
Example: start then poll
Find, match, and enrich people. Provide a people list (list mode) or a filter (search mode) and compose the response with select.
On v7 and earlier this endpoint is synchronous: one call returns the people.
On v8 and later it is asynchronous in both modes. Send a people or filter body to start a background job — the response returns a request_id and status: "pending", and no credits are charged yet (the request is validated and your balance pre-checked, so you still get a 400/402 up front). Then send { "request_id": "..." } to the same endpoint to poll: you get status pending/running until it finishes, then succeeded (with the full people/total result) or failed. Credits are charged once, on the first succeeded poll; repeat polls report credits_used: 0. The async response adds request_id and status fields.
Maximum number of people to return (filter mode only; ignored when people is provided).
10Number of results to skip (filter mode only; ignored when people is provided).
0Column to order by (filter mode only): start_date (current role start), job_level (seniority rank), or person_score. person_score sorts people by how well they match your ideal customer profile (ICP) and includes — and charges for — the person_score attribute on every row; it requires the filter to resolve to exactly one organization and an ICP configured for your account, and only supports descending order. Default: Sumble's standard people ordering.
Sort direction; DESC when omitted.
(v8 only) Id of a previously started async request (returned by the kickoff call). Provide this alone to poll for the status and result.
Successful Response
(v8 only) Id of the async request. Poll POST /people with this id to retrieve the status and result.
(v8 only) Request status: pending, running, succeeded, or failed. Null on the synchronous (<= v7) endpoint.
List mode only: how many input entries resolved to a Sumble person.
Validation Error
POST /v9/people HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"filter": {
"organization_ids": [
1726684
]
},
"select": {}
}{
"id": "019980d2-bc85-7571-9d60-7bc1d3084249",
"credits_used": 8,
"credits_remaining": 69156,
"total": 113,
"source_data_url": "https://sumble.com/l/org/xhXARFaWtJL/people",
"people": [
{
"person_id": 181438858,
"sumble_url": "https://sumble.com/l/person/MBwjfWREd8Pz",
"attributes": {
"name": "Akash Gajjar",
"linkedin_url": "https://www.linkedin.com/in/akashagajjar",
"job_title": "Software Engineer",
"job_function": "Software Engineer",
"job_level": "Individual Contributor",
"location": "Gainesville, Florida, United States",
"country": "United States",
"current_employer": {
"organization_id": 1726684,
"name": "Sumble",
"start_date": "2024-08",
"sumble_url": "https://sumble.com/l/org/xhXARFaWtJL"
},
"technologies": [
{
"name": "Kubernetes",
"slug": "kubernetes"
},
{
"name": "Python",
"slug": "python"
}
],
"person_score": {
"value": 72.4,
"skill_contribution": 14.8,
"job_function_contribution": 28.2,
"seniority_contribution": 29.4,
"matched_features": [
{
"name": "Software Engineer",
"slug": "software-engineer",
"match_type": "job_function",
"contribution": 28.2
},
{
"name": "Kubernetes",
"slug": "kubernetes",
"match_type": "technology",
"contribution": 9.1
}
]
}
},
"related_people": {
"managers": [
{
"person_id": 169860318,
"sumble_url": "https://sumble.com/l/person/yxGWeupK3yPj",
"attributes": {
"name": "Jared Nightingale",
"job_title": "Business Operations Specialist"
}
}
],
"direct_reports": []
}
}
]
}Last updated