Sumble people API
The people API from Sumble — 1 operation(s) for people.
OpenAPI Specification
openapi: 3.1.0
info:
title: Sumble contact-lists people API
description: The official Sumble API for programmatic enrichment.
contact:
name: Sumble
email: support@sumble.com
version: v9
servers:
- url: https://api.sumble.com
tags:
- name: people
paths:
/v9/people:
post:
tags:
- people
summary: Unified people endpoint
description: '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.'
operationId: enrich_people_unified__api_version__people_post
security:
- api_token: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichPeopleRequest'
examples:
by_org_ids:
summary: People at specific organizations (no attributes requested)
value:
filter:
organization_ids:
- 1726684
select: {}
by_list_with_query:
summary: Saved organization list + advanced query, all attributes
value:
filter:
organization_list_id: 123
query:
query: job_function EQ 'Engineer' AND technology EQ 'kubernetes' AND country EQ 'US'
select:
attributes:
- name
- linkedin_url
- job_title
- job_function
- job_level
- location
- country
- current_employer
- technologies
limit: 50
by_org_person_score:
summary: People at one organization, all attributes, sorted by person score (requires an ICP)
value:
filter:
organization_ids:
- 1726684
select:
attributes: all
order_by_column: person_score
limit: 25
by_people_list:
summary: 'List mode: resolve and enrich specific people'
value:
people:
- person_id: 181438858
- linkedin_url: https://www.linkedin.com/in/jared-nightingale
- email: lou@sumble.com
select:
attributes:
- name
- email
- phone
- job_title
- current_employer
related_people:
direction:
- managers
- direct_reports
attributes:
- name
- job_title
poll:
summary: (v8+) Poll a started request for its result
value:
request_id: 019980d2-bc85-7571-9d60-7bc1d3084249
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichPeopleResponse'
example:
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: []
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
PersonInput:
properties:
person_id:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Person Id
description: Person id on Sumble. When set, it identifies the person directly and `linkedin_url`/`email` are ignored.
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
description: 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:
anyOf:
- type: string
- type: 'null'
title: Email
description: 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.
additionalProperties: false
type: object
title: PersonInput
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CurrentEmployer:
properties:
organization_id:
type: integer
title: Organization Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
start_date:
anyOf:
- type: string
- type: 'null'
title: Start Date
description: Start of the person's current role (YYYY-MM).
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: Link to the organization's Sumble profile page.
type: object
required:
- organization_id
title: CurrentEmployer
RelatedPeopleResult:
properties:
managers:
anyOf:
- items:
$ref: '#/components/schemas/RelatedPersonRow'
type: array
- type: 'null'
title: Managers
description: Inferred managers; present only when requested.
direct_reports:
anyOf:
- items:
$ref: '#/components/schemas/RelatedPersonRow'
type: array
- type: 'null'
title: Direct Reports
description: Inferred direct reports; present only when requested.
type: object
title: RelatedPeopleResult
PersonRow:
properties:
input:
anyOf:
- $ref: '#/components/schemas/PersonInput'
- type: 'null'
description: The input entry this row corresponds to (list mode only).
person_id:
anyOf:
- type: integer
- type: 'null'
title: Person Id
description: Absent when the input entry didn't resolve to a person.
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: Link to the person's Sumble profile page.
attributes:
anyOf:
- $ref: '#/components/schemas/PersonAttributes'
- type: 'null'
description: The requested person-level attributes; absent when none resolve.
related_people:
anyOf:
- $ref: '#/components/schemas/RelatedPeopleResult'
- type: 'null'
description: Requested related people (match mode with `select.related_people`).
type: object
title: PersonRow
PersonScoreFeature:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
match_type:
type: string
enum:
- technology
- job_function
title: Match Type
contribution:
type: number
title: Contribution
description: Points of the 0-100 score attributable to this feature.
type: object
required:
- name
- slug
- match_type
- contribution
title: PersonScoreFeature
RelatedPeopleSelection:
properties:
direction:
items:
type: string
enum:
- managers
- direct_reports
type: array
minItems: 1
title: Direction
description: Which hierarchy direction(s) to return.
attributes:
anyOf:
- items:
type: string
enum:
- name
- email
- phone
- linkedin_url
- job_title
- job_function
- job_level
- location
- country
- current_employer
- technologies
- person_score
- confidence
type: array
- type: string
const: all
title: Attributes
description: 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.
default: []
additionalProperties: false
type: object
required:
- direction
title: RelatedPeopleSelection
PeopleFilter:
properties:
organization_ids:
anyOf:
- items:
type: integer
type: array
maxItems: 1000
minItems: 1
- type: 'null'
title: Organization Ids
description: 'Sumble organization ids to search within. People queries are organization-scoped: provide this and/or `organization_list_id`.'
organization_list_id:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Organization List Id
description: 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:
anyOf:
- $ref: '#/components/schemas/Query'
- type: 'null'
description: Advanced query narrowing the people returned (job functions, technologies, job levels, locations, ...).
additionalProperties: false
type: object
title: PeopleFilter
Query:
properties:
query:
type: string
title: Query
type: object
required:
- query
title: Query
RelatedPersonRow:
properties:
person_id:
type: integer
title: Person Id
sumble_url:
type: string
maxLength: 2083
minLength: 1
format: uri
title: Sumble Url
description: Link to the person's Sumble profile page.
confidence:
anyOf:
- $ref: '#/components/schemas/RelatedPersonConfidence'
- type: 'null'
description: 'Why this person was returned: confidence score (0-1) with per-category and per-feature breakdowns. Present when the `confidence` attribute is requested. Not the ICP-based `person_score`.'
attributes:
anyOf:
- $ref: '#/components/schemas/PersonAttributes'
- type: 'null'
description: The requested person-level attributes; absent when none resolve.
type: object
required:
- person_id
- sumble_url
title: RelatedPersonRow
PeopleSelect:
properties:
attributes:
anyOf:
- items:
type: string
enum:
- name
- email
- phone
- linkedin_url
- job_title
- job_function
- job_level
- location
- country
- current_employer
- technologies
- person_score
- confidence
type: array
- type: string
const: all
title: Attributes
description: 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.
default: []
related_people:
anyOf:
- $ref: '#/components/schemas/RelatedPeopleSelection'
- type: 'null'
description: Also return people related to each matched person, up or down the org hierarchy. Relationships are inferred from org structure and seniority (technology, job function, team, location and job-level similarity), not actual reporting lines. Only available in match mode (`people`), for at most 25 people per request. Each related person returned costs 1 credit.
additionalProperties: false
type: object
title: PeopleSelect
PersonScore:
properties:
value:
type: number
title: Value
description: How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below.
skill_contribution:
type: number
title: Skill Contribution
description: Points from technologies the person uses that match your ICP.
job_function_contribution:
type: number
title: Job Function Contribution
description: Points from the person's job function matching your ICP.
seniority_contribution:
type: number
title: Seniority Contribution
description: Points from the person's job level (seniority).
matched_features:
items:
$ref: '#/components/schemas/PersonScoreFeature'
type: array
title: Matched Features
description: The matched technologies and job functions behind the skill and job-function contributions, highest contribution first.
type: object
required:
- value
- skill_contribution
- job_function_contribution
- seniority_contribution
- matched_features
title: PersonScore
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
EnrichPeopleResponse:
properties:
id:
type: string
format: uuid
title: Id
credits_used:
type: integer
title: Credits Used
credits_remaining:
type: integer
title: Credits Remaining
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: (v8 only) Id of the async request. Poll POST /people with this id to retrieve the status and result.
status:
anyOf:
- type: string
- type: 'null'
title: Status
description: '(v8 only) Request status: pending, running, succeeded, or failed. Null on the synchronous (<= v7) endpoint.'
people:
anyOf:
- items:
$ref: '#/components/schemas/PersonRow'
type: array
- type: 'null'
title: People
matched_count:
anyOf:
- type: integer
- type: 'null'
title: Matched Count
description: 'List mode only: how many input entries resolved to a Sumble person.'
total:
anyOf:
- type: integer
- type: 'null'
title: Total
source_data_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Source Data Url
type: object
required:
- id
- credits_used
- credits_remaining
title: EnrichPeopleResponse
EnrichPeopleRequest:
properties:
people:
anyOf:
- items:
$ref: '#/components/schemas/PersonInput'
type: array
maxItems: 1000
minItems: 1
- type: 'null'
title: People
description: List of people to resolve and enrich. One result row per entry, in input order. Mutually exclusive with `filter`.
filter:
anyOf:
- $ref: '#/components/schemas/PeopleFilter'
- type: 'null'
description: Query selecting the people to return. Mutually exclusive with `people`.
select:
$ref: '#/components/schemas/PeopleSelect'
description: Dictates exactly which attributes are returned.
limit:
type: integer
maximum: 200.0
minimum: 1.0
title: Limit
description: Maximum number of people to return (filter mode only; ignored when `people` is provided).
default: 10
offset:
type: integer
maximum: 10000.0
minimum: 0.0
title: Offset
description: Number of results to skip (filter mode only; ignored when `people` is provided).
default: 0
order_by_column:
anyOf:
- type: string
enum:
- person_score
- start_date
- job_level
- type: 'null'
title: Order By Column
description: '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:
anyOf:
- type: string
enum:
- ASC
- DESC
- type: 'null'
title: Order By Direction
description: Sort direction; DESC when omitted.
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: (v8 only) Id of a previously started async request (returned by the kickoff call). Provide this alone to poll for the status and result.
additionalProperties: false
type: object
title: EnrichPeopleRequest
PersonTechnology:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
type: object
required:
- name
- slug
title: PersonTechnology
RelatedPersonConfidence:
properties:
score:
type: number
title: Score
description: 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:
type: number
title: Technology Contribution
description: Share from technologies shared with the source.
job_function_contribution:
type: number
title: Job Function Contribution
description: Share from matching job functions.
team_contribution:
type: number
title: Team Contribution
description: Share from shared teams.
location_contribution:
type: number
title: Location Contribution
description: Share from matching locations.
title_similarity_contribution:
type: number
title: Title Similarity Contribution
description: Share from semantic similarity between job titles.
matched_features:
items:
$ref: '#/components/schemas/RelatedPersonConfidenceFeature'
type: array
title: Matched Features
description: The specific matched features behind the contributions, highest contribution first.
type: object
required:
- score
- technology_contribution
- job_function_contribution
- team_contribution
- location_contribution
- title_similarity_contribution
- matched_features
title: RelatedPersonConfidence
PersonAttributes:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
email:
anyOf:
- type: string
- type: 'null'
title: Email
description: Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free.
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
description: Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free.
linkedin_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Linkedin Url
job_title:
anyOf:
- type: string
- type: 'null'
title: Job Title
job_function:
anyOf:
- type: string
- type: 'null'
title: Job Function
job_level:
anyOf:
- type: string
- type: 'null'
title: Job Level
location:
anyOf:
- type: string
- type: 'null'
title: Location
country:
anyOf:
- type: string
- type: 'null'
title: Country
current_employer:
anyOf:
- $ref: '#/components/schemas/CurrentEmployer'
- type: 'null'
technologies:
anyOf:
- items:
$ref: '#/components/schemas/PersonTechnology'
type: array
- type: 'null'
title: Technologies
description: 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.
person_score:
anyOf:
- $ref: '#/components/schemas/PersonScore'
- type: 'null'
description: 'How well the person matches your ideal customer profile (ICP), 0-100, with a per-feature breakdown. Priced like other paid attributes. Filter mode only; selecting it explicitly requires the filter to resolve to exactly one organization and an ICP configured for your account (`attributes: "all"` skips it instead when unavailable). Included automatically when sorting with `order_by_column="person_score"`.'
type: object
title: PersonAttributes
RelatedPersonConfidenceFeature:
properties:
match_type:
type: string
enum:
- technology
- job_function
- team
- location
- title_similarity
title: Match Type
name:
type: string
title: Name
description: The matched feature's name; for title_similarity, the related person's own job title.
slug:
anyOf:
- type: string
- type: 'null'
title: Slug
description: Null for location and title_similarity matches.
contribution:
type: number
title: Contribution
description: Share of the confidence score attributable to this feature.
type: object
required:
- match_type
- name
- contribution
title: RelatedPersonConfidenceFeature
securitySchemes:
api_token:
type: http
scheme: bearer