Sign in

v1

latestOpenAPI 3.1.02026-07-23138880.6 KB
people

Unified people endpoint

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.

post/v9/people

Request body

limitinteger

Maximum number of people to return (filter mode only; ignored when people is provided).

offsetinteger

Number of results to skip (filter mode only; ignored when people is provided).

order_by_column'person_score' | 'start_date' | 'job_level' nullable

Column 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.

order_by_direction'ASC' | 'DESC' nullable

Sort direction; DESC when omitted.

request_idstring nullable

(v8 only) Id of a previously started async request (returned by the kickoff call). Provide this alone to poll for the status and result.

Response

Successful Response

idstring uuid required
credits_usedinteger required
credits_remaininginteger required
request_idstring nullable

(v8 only) Id of the async request. Poll POST /people with this id to retrieve the status and result.

statusstring nullable

(v8 only) Request status: pending, running, succeeded, or failed. Null on the synchronous (<= v7) endpoint.

matched_countinteger nullable

List mode only: how many input entries resolved to a Sumble person.

totalinteger nullable
source_data_urlstring uri nullable