For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

    • Entries identified by email may also carry an optional name. It isn't an identifier — an entry with only a name is rejected — but it noticeably improves email resolution, especially for addresses like firstname@company.com where 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.

  • filter selects people using an advanced query or search. Use organization_ids, up to 1,000, and/or a saved organization_list_id to scope either approach to those organizations. Covers the previous find flow.

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.

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.

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_ids enforces the employer and locations enforces 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 attributes experience and summary, 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.

    • 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. experience is the person's LinkedIn-style role history, newest first: title, start_date and end_date (YYYY-MM, null end for a current role), duration, location, the person's own description of the role, and an employer shaped like current_employer (organization_id, slug, and sumble_url when Sumble knows the organization, plus the employer's name and linkedin_url from the profile). summary is the profile's "About" section as the person wrote it.

    • person_score is 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 by person_score is descending only, and it adds person_score to every returned row, charged like any paid attribute.

  • 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. Add confidence to 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 (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.

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

Field
Type
Description

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:

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.

file

object

Metadata and download URL for the file requested with file_name; present when the job succeeds. See File downloads.

error

object

Why the job failed. Present only when status is failed. See Failed requests.

Failed requests

A failed poll response carries an error object:

Field
Type
Description

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

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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
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
post/v9/people
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