People

Find, match, and enrich people

The single endpoint for working with people. Provide either a list of people to resolve (list mode) or an organization-scoped filter (search mode), 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 Sumble person_id, a linkedin_url, or a work email (used in that order of precedence). Limited to 25 entries when requesting contact attributes, related people, or email identifiers. Covers the previous enrich and find-related-people flows.

• filter — the organizations whose people to return: organization_ids (up to 1,000) and/or a saved organization_list_id, optionally narrowed by an advanced query (job functions, technologies, job levels, locations, and more). Covers the previous find flow.

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.

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, person_score, and the contact attributes email and phone. person_id and sumble_url are always included for free.

  • The contact attributes email and phone must be requested explicitly — they are never part of "all" — and are only available in list mode, for up to 25 people per request.

  • person_score is your ICP match score (0–100) with its contribution breakdown. It requires filter mode with exactly one organization in scope and an ICP configured; "all" includes it opportunistically when those requirements are met.

• related_people — inferred managers and/or direct reports for each matched person. Choose the direction (managers, direct_reports) and which attributes to return for them. Available in list mode only, for up to 25 people per request.

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 (name is free), plus

• 1 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 email to 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.

1

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.

2

Poll for the result

POST /people with { "request_id": "..." }. While the job runs you get status: "pending" or "running". When it finishes you get a terminal status and, on success, the full result (people, total, and the other fields).

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.

Poll request body

Field	Type	Description
request_id	string	The request_id returned when the job was started. Provide this alone to poll — don't send people or filter 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 errored after retries.

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:

Field	Type	Description
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.

Example: start then poll

Start

curl -X POST https://sumble.com/paid-api/v9/people \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "people": [ { "email": "[e-mail]" } ], "select": { "attributes": ["name", "job_title"] } }'
# -> { "request_id": "019d...", "status": "pending", "credits_used": 0, "credits_remaining": 6571 }

Poll

Unified people endpoint

post

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.

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

limitinteger · min: 1 · max: 200Optional

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

Default: 10

offsetinteger · max: 10000Optional

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

Default: 0

order_by_columnstring · enum · nullableOptional

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.

Possible values:

order_by_directionstring · enum · nullableOptional

Sort direction; DESC when omitted.

Possible values:

request_idstring · nullableOptional

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

Responses

200

Successful Response

application/json

idstring · uuidRequired

credits_usedintegerRequired

credits_remainingintegerRequired

request_idstring · nullableOptional

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

statusstring · nullableOptional

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

matched_countinteger · nullableOptional

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

totalinteger · nullableOptional

source_data_urlstring · uri · min: 1 · max: 2083 · nullableOptional

422

Validation Error

application/json

post/v9/people

HTTPcURLJavaScriptPython

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": {}
}

People at specific organizations (no attributes requested)Saved organization list + advanced query, all attributesPeople at one organization, all attributes, sorted by person score (requires an ICP)List mode: resolve and enrich specific people(v8+) Poll a started request for its result

{
  "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": []
      }
    }
  ]
}