---
title: "Unified people endpoint"
method: POST
path: "/v9/people"
tags: ["people"]
---

# Unified people endpoint

`POST /v9/people`

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.

## Request body

- EnrichPeopleRequest
  - `people` PersonInput[], nullable — List of people to resolve and enrich. One result row per entry, in input order. Mutually exclusive with `filter`.
    - `person_id` integer, nullable — Person id on Sumble. When set, it identifies the person directly and `linkedin_url`/`email` are ignored.
    - `linkedin_url` string, nullable — LinkedIn profile URL of the person, e.g. 'https://www.linkedin.com/in/<slug>'. Entries whose URL is not a profile URL come back unmatched. Takes precedence over `email`.
    - `email` string, nullable — Work email of the person, resolved via reverse enrichment. Costs 20 extra credits when it resolves to a returned person; emails that don't resolve come back unmatched, free. Only used when neither `person_id` nor `linkedin_url` is provided.
  - `filter` PeopleFilter
    - `organization_ids` integer[], nullable — Sumble organization ids to search within. People queries are organization-scoped: provide this and/or `organization_list_id`.
    - `organization_list_id` integer, nullable — Id of one of your saved organization lists (see /organization-lists) whose organizations to search within. Combined with `organization_ids` when both are provided.
    - `query` Query
      - `query` string, required
  - `select` PeopleSelect
    - `attributes` union — Person-level attributes to include, or 'all' for every attribute-priced attribute. Off by default. 'all' excludes contact attributes (email, phone), which must be requested explicitly, and includes `person_score` only when it is available (filter mode with exactly one organization in scope and an ICP configured for your account) — otherwise it is skipped, not an error. When `person_score` is included and no `order_by_column` is set, results are ordered by it. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.
      - string[]
      - 'all'
    - `related_people` RelatedPeopleSelection
      - `direction` string[], required — Which hierarchy direction(s) to return.
      - `attributes` union — Person-level attributes to include for each related person, or 'all' for every attribute available here. Contact attributes (email, phone) and `person_score` are not available here; `confidence` (the inferred relationship's score breakdown) is only available here.
        - string[]
        - 'all'
  - `limit` integer — Maximum number of people to return (filter mode only; ignored when `people` is provided).
  - `offset` integer — 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_id` string, 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 `200`

Successful Response

- EnrichPeopleResponse
  - `id` string, uuid, required
  - `credits_used` integer, required
  - `credits_remaining` integer, required
  - `request_id` string, nullable — (v8 only) Id of the async request. Poll POST /people with this id to retrieve the status and result.
  - `status` string, nullable — (v8 only) Request status: pending, running, succeeded, or failed. Null on the synchronous (<= v7) endpoint.
  - `people` PersonRow[], nullable
    - `input` PersonInput
      - `person_id` integer, nullable — Person id on Sumble. When set, it identifies the person directly and `linkedin_url`/`email` are ignored.
      - `linkedin_url` string, nullable — LinkedIn profile URL of the person, e.g. 'https://www.linkedin.com/in/<slug>'. Entries whose URL is not a profile URL come back unmatched. Takes precedence over `email`.
      - `email` string, nullable — Work email of the person, resolved via reverse enrichment. Costs 20 extra credits when it resolves to a returned person; emails that don't resolve come back unmatched, free. Only used when neither `person_id` nor `linkedin_url` is provided.
    - `person_id` integer, nullable — Absent when the input entry didn't resolve to a person.
    - `sumble_url` string, uri, nullable — Link to the person's Sumble profile page.
    - `attributes` PersonAttributes
      - `name` string, nullable
      - `email` string, nullable — Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free.
      - `phone` string, nullable — Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free.
      - `linkedin_url` string, uri, nullable
      - `job_title` string, nullable
      - `job_function` string, nullable
      - `job_level` string, nullable
      - `location` string, nullable
      - `country` string, nullable
      - `current_employer` CurrentEmployer
        - `organization_id` integer, required
        - `name` string, nullable
        - `start_date` string, nullable — Start of the person's current role (YYYY-MM).
        - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
      - `technologies` PersonTechnology[], nullable — Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology.
        - `name` string, required
        - `slug` string, required
      - `person_score` PersonScore
        - `value` number, required — How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below.
        - `skill_contribution` number, required — Points from technologies the person uses that match your ICP.
        - `job_function_contribution` number, required — Points from the person's job function matching your ICP.
        - `seniority_contribution` number, required — Points from the person's job level (seniority).
        - `matched_features` PersonScoreFeature[], required — The matched technologies and job functions behind the skill and job-function contributions, highest contribution first.
          - `name` string, required
          - `slug` string, required
          - `match_type` 'technology' | 'job_function', required
          - `contribution` number, required — Points of the 0-100 score attributable to this feature.
    - `related_people` RelatedPeopleResult
      - `managers` RelatedPersonRow[], nullable — Inferred managers; present only when requested.
        - `person_id` integer, required
        - `sumble_url` string, uri, required — Link to the person's Sumble profile page.
        - `confidence` RelatedPersonConfidence
          - `score` number, required — How strongly this person relates to the source person (people endpoint) or job posting (jobs endpoint), 0-1. Sum of the five contributions below. Measures similarity on shared features (technologies, job functions, teams, locations, job titles) — unrelated to the ICP-based `person_score` attribute.
          - `technology_contribution` number, required — Share from technologies shared with the source.
          - `job_function_contribution` number, required — Share from matching job functions.
          - `team_contribution` number, required — Share from shared teams.
          - `location_contribution` number, required — Share from matching locations.
          - `title_similarity_contribution` number, required — Share from semantic similarity between job titles.
          - `matched_features` RelatedPersonConfidenceFeature[], required — The specific matched features behind the contributions, highest contribution first.
            - `match_type` 'technology' | 'job_function' | 'team' | 'location' | 'title_similarity', required
            - `name` string, required — The matched feature's name; for title_similarity, the related person's own job title.
            - `slug` string, nullable — Null for location and title_similarity matches.
            - `contribution` number, required — Share of the confidence score attributable to this feature.
        - `attributes` PersonAttributes
          - `name` string, nullable
          - `email` string, nullable — Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free.
          - `phone` string, nullable — Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free.
          - `linkedin_url` string, uri, nullable
          - `job_title` string, nullable
          - `job_function` string, nullable
          - `job_level` string, nullable
          - `location` string, nullable
          - `country` string, nullable
          - `current_employer` CurrentEmployer
            - `organization_id` integer, required
            - `name` string, nullable
            - `start_date` string, nullable — Start of the person's current role (YYYY-MM).
            - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
          - `technologies` PersonTechnology[], nullable — Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology.
            - `name` string, required
            - `slug` string, required
          - `person_score` PersonScore
            - `value` number, required — How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below.
            - `skill_contribution` number, required — Points from technologies the person uses that match your ICP.
            - `job_function_contribution` number, required — Points from the person's job function matching your ICP.
            - `seniority_contribution` number, required — Points from the person's job level (seniority).
            - `matched_features` PersonScoreFeature[], required — The matched technologies and job functions behind the skill and job-function contributions, highest contribution first.
              - …
      - `direct_reports` RelatedPersonRow[], nullable — Inferred direct reports; present only when requested.
        - `person_id` integer, required
        - `sumble_url` string, uri, required — Link to the person's Sumble profile page.
        - `confidence` RelatedPersonConfidence
          - `score` number, required — How strongly this person relates to the source person (people endpoint) or job posting (jobs endpoint), 0-1. Sum of the five contributions below. Measures similarity on shared features (technologies, job functions, teams, locations, job titles) — unrelated to the ICP-based `person_score` attribute.
          - `technology_contribution` number, required — Share from technologies shared with the source.
          - `job_function_contribution` number, required — Share from matching job functions.
          - `team_contribution` number, required — Share from shared teams.
          - `location_contribution` number, required — Share from matching locations.
          - `title_similarity_contribution` number, required — Share from semantic similarity between job titles.
          - `matched_features` RelatedPersonConfidenceFeature[], required — The specific matched features behind the contributions, highest contribution first.
            - `match_type` 'technology' | 'job_function' | 'team' | 'location' | 'title_similarity', required
            - `name` string, required — The matched feature's name; for title_similarity, the related person's own job title.
            - `slug` string, nullable — Null for location and title_similarity matches.
            - `contribution` number, required — Share of the confidence score attributable to this feature.
        - `attributes` PersonAttributes
          - `name` string, nullable
          - `email` string, nullable — Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free.
          - `phone` string, nullable — Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free.
          - `linkedin_url` string, uri, nullable
          - `job_title` string, nullable
          - `job_function` string, nullable
          - `job_level` string, nullable
          - `location` string, nullable
          - `country` string, nullable
          - `current_employer` CurrentEmployer
            - `organization_id` integer, required
            - `name` string, nullable
            - `start_date` string, nullable — Start of the person's current role (YYYY-MM).
            - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
          - `technologies` PersonTechnology[], nullable — Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology.
            - `name` string, required
            - `slug` string, required
          - `person_score` PersonScore
            - `value` number, required — How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below.
            - `skill_contribution` number, required — Points from technologies the person uses that match your ICP.
            - `job_function_contribution` number, required — Points from the person's job function matching your ICP.
            - `seniority_contribution` number, required — Points from the person's job level (seniority).
            - `matched_features` PersonScoreFeature[], required — The matched technologies and job functions behind the skill and job-function contributions, highest contribution first.
              - …
  - `matched_count` integer, nullable — List mode only: how many input entries resolved to a Sumble person.
  - `total` integer, nullable
  - `source_data_url` string, uri, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/sumble/apis/sumble-api.md) · [All operations](https://skmtc.net/sumble/apis/sumble-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sumble/sumble-api/revisions/fbfd97abec00/schema)