Sumble jobs API
The jobs API from Sumble — 2 operation(s) for jobs.
OpenAPI Specification
openapi: 3.1.0
info:
title: Sumble contact-lists jobs 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: jobs
paths:
/v9/jobs/title-lookup:
post:
tags:
- jobs
summary: Look up the function and level for job titles
operationId: lookup_job_titles__api_version__jobs_title_lookup_post
security:
- api_token: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupTitlesRequest'
example:
titles:
- software engineer
- senior data scientist
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LookupTitlesResponse'
example:
id: 019c9529-9d27-7e16-b721-76d18c339e3e
credits_used: 1
credits_remaining: 999
matched_count: 2
results:
- input: software engineer
job_function:
id: 97
slug: software-engineer
name: Software Engineer
job_level:
id: -1
name: Individual Contributor
level_rank: 0
- input: senior data scientist
job_function:
id: 74
slug: data-scientist
name: Data Scientist
job_level:
id: 18
name: Senior
level_rank: 1
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v9/jobs:
post:
tags:
- jobs
summary: Unified jobs endpoint
operationId: enrich_jobs_unified__api_version__jobs_post
security:
- api_token: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichJobsRequest'
examples:
by_org_ids:
summary: Jobs at specific organizations (no attributes requested)
value:
filter:
organization_ids:
- 1726684
select: {}
by_query:
summary: Corpus-wide advanced query, some attributes
value:
filter:
query:
query: technology EQ 'kubernetes' AND job_function EQ 'Data Engineer' AND hiring_period EQ '6mo'
select:
attributes:
- title
- location
- posted_date
- organization
limit: 50
with_extracted_entities:
summary: Org-scoped jobs with extracted entities (+1 credit each per job)
value:
filter:
organization_ids:
- 1726684
select:
attributes:
- title
- technologies
- teams
- job_functions
- job_levels
- projects
limit: 10
by_list_all_attributes:
summary: Saved organization list + query, all attributes (includes the full description and extracted entities)
value:
filter:
organization_list_id: 123
query:
query: technology EQ 'react'
select:
attributes: all
limit: 10
by_job_ids:
summary: 'List mode: enrich specific jobs by id'
value:
jobs:
- job_id: 95107725
- job_id: 12345
select:
attributes:
- title
- description
- organization
related_people:
attributes:
- name
- job_title
limit: 3
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichJobsResponse'
examples:
filter_mode:
summary: Filter mode
value:
id: 019980d2-bc85-7571-9d60-7bc1d3084249
credits_used: 9
credits_remaining: 69156
total: 113
source_data_url: https://sumble.com/l/org/xhXARFaWtJL/jobs
jobs:
- job_id: 95107725
sumble_url: https://sumble.com/l/job/fdYksIHVnJ
attributes:
title: gtm engineer
location: United States
posted_date: '2026-02-20T12:20:03.687777Z'
organization:
organization_id: 1726684
name: Sumble
domain: sumble.com
sumble_url: https://sumble.com/l/org/xhXARFaWtJL
technologies:
- name: Kubernetes
slug: kubernetes
used: true
sumble_url: https://sumble.com/l/org/aQw2Ee9TrV/jobs
- name: Salesforce
slug: salesforce
used: false
sumble_url: https://sumble.com/l/org/bRx3Ff0UsW/jobs
teams:
- team_id: 4242
name: Platform Engineering
slug: platform-engineering
sumble_url: https://sumble.com/l/team/aBcDeF
job_functions:
- name: Data Engineer
slug: data-engineer
sumble_url: https://sumble.com/l/org/cSy4Gg1VtX/jobs
job_levels:
- name: Senior
projects:
- name: Cloud Migration
slug: cloud-migration
goal: Migrate on-prem workloads to GCP
sumble_url: https://sumble.com/l/org/dTz5Hh2WuY/jobs
list_mode:
summary: List mode (one matched, one unmatched entry)
value:
id: 019980d2-bc85-7571-9d60-7bc1d3084249
credits_used: 4
credits_remaining: 69152
matched_count: 1
total: 2
jobs:
- input:
job_id: 95107725
job_id: 95107725
sumble_url: https://sumble.com/l/job/fdYksIHVnJ
attributes:
title: gtm engineer
description: Sumble helps go-to-market teams win with deep account intelligence...
organization:
organization_id: 1726684
name: Sumble
domain: sumble.com
sumble_url: https://sumble.com/l/org/xhXARFaWtJL
related_people:
- person_id: 169860318
sumble_url: https://sumble.com/l/person/yxGWeupK3yPj
attributes:
name: Jared Nightingale
job_title: Business Operations Specialist
- input:
job_id: 12345
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
JobTeam:
properties:
team_id:
type: integer
title: Team Id
name:
type: string
title: Name
slug:
type: string
title: Slug
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: Link to the team's Sumble page.
type: object
required:
- team_id
- name
- slug
title: JobTeam
JobAttributes:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
description:
anyOf:
- type: string
- type: 'null'
title: Description
location:
anyOf:
- type: string
- type: 'null'
title: Location
posted_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Posted Date
organization:
anyOf:
- $ref: '#/components/schemas/JobOrganization'
- type: 'null'
technologies:
anyOf:
- items:
$ref: '#/components/schemas/JobTechnology'
type: array
- type: 'null'
title: Technologies
description: All technologies extracted from the posting; empty list when requested but none were extracted.
teams:
anyOf:
- items:
$ref: '#/components/schemas/JobTeam'
type: array
- type: 'null'
title: Teams
description: Teams extracted from the posting; empty list when requested but none were extracted.
job_functions:
anyOf:
- items:
$ref: '#/components/schemas/app__schemas__paid_api__jobs_unified__JobFunction'
type: array
- type: 'null'
title: Job Functions
description: Job functions classified from the posting; empty list when requested but none were classified.
job_levels:
anyOf:
- items:
$ref: '#/components/schemas/app__schemas__paid_api__jobs_unified__JobLevel'
type: array
- type: 'null'
title: Job Levels
description: Seniority levels classified from the posting; empty list when requested but none were classified.
projects:
anyOf:
- items:
$ref: '#/components/schemas/JobProject'
type: array
- type: 'null'
title: Projects
description: Projects extracted from the posting; empty list when requested but none were extracted.
type: object
title: JobAttributes
LookupTitlesRequest:
properties:
titles:
items:
type: string
type: array
maxItems: 1000
minItems: 1
title: Titles
description: List of job titles to look up
type: object
required:
- titles
title: LookupTitlesRequest
JobsSelect:
properties:
attributes:
anyOf:
- items:
type: string
enum:
- title
- description
- location
- posted_date
- organization
- technologies
- teams
- job_functions
- job_levels
- projects
type: array
- type: string
const: all
title: Attributes
description: Job attributes to include, or 'all' for every available attribute (including the full `description`). Off by default. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.
default: []
related_people:
anyOf:
- $ref: '#/components/schemas/JobRelatedPeopleSelection'
- type: 'null'
description: Also return the people likely involved in each job's hiring — scored hiring managers and team members at the posting organization, inferred from team, job function, location and technology similarity, not actual reporting lines. Available in both modes, for at most 200 jobs per request. Each related person returned costs 1 credit.
additionalProperties: false
type: object
title: JobsSelect
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
LookupTitlesResponse:
properties:
id:
type: string
format: uuid
title: Id
credits_used:
type: integer
title: Credits Used
credits_remaining:
type: integer
title: Credits Remaining
matched_count:
type: integer
title: Matched Count
results:
items:
$ref: '#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__LookupResult'
type: array
title: Results
type: object
required:
- id
- credits_used
- credits_remaining
- matched_count
- results
title: LookupTitlesResponse
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
JobRow:
properties:
input:
anyOf:
- $ref: '#/components/schemas/JobInput'
- type: 'null'
description: The input entry this row corresponds to (list mode only).
job_id:
anyOf:
- type: integer
- type: 'null'
title: Job Id
description: Absent when the input entry didn't match a Sumble job.
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: Link to the job posting's Sumble page.
attributes:
anyOf:
- $ref: '#/components/schemas/JobAttributes'
- type: 'null'
description: The requested job attributes; absent when none are requested.
related_people:
anyOf:
- items:
$ref: '#/components/schemas/RelatedPersonRow'
type: array
- type: 'null'
title: Related People
description: Scored hiring managers / team members for the job. Present (possibly empty) when `select.related_people` is requested and the job matched; absent otherwise.
type: object
title: JobRow
app__schemas__paid_api__jobs_unified__JobLevel:
properties:
name:
type: string
title: Name
type: object
required:
- name
title: JobLevel
JobProject:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
goal:
anyOf:
- type: string
- type: 'null'
title: Goal
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: The posting organization's jobs page filtered to this project.
type: object
required:
- name
- slug
title: JobProject
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
app__schemas__paid_api__jobs_unified__JobFunction:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: The posting organization's jobs page filtered to this job function.
type: object
required:
- name
- slug
title: JobFunction
JobInput:
properties:
job_id:
type: integer
minimum: 1.0
title: Job Id
description: Job id on Sumble.
additionalProperties: false
type: object
required:
- job_id
title: JobInput
JobOrganization:
properties:
organization_id:
type: integer
title: Organization Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
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: JobOrganization
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
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
app__schemas__paid_api__jobs__LookupTitlesResponse__JobLevel:
properties:
id:
type: integer
title: Id
name:
type: string
title: Name
level_rank:
type: integer
title: Level Rank
type: object
required:
- id
- name
- level_rank
title: JobLevel
JobTechnology:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
used:
type: boolean
title: Used
description: True when the posting indicates the technology is used by the team, not merely mentioned.
sumble_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Sumble Url
description: The posting organization's jobs page filtered to this technology.
type: object
required:
- name
- slug
- used
title: JobTechnology
EnrichJobsResponse:
properties:
id:
type: string
format: uuid
title: Id
credits_used:
type: integer
title: Credits Used
credits_remaining:
type: integer
title: Credits Remaining
jobs:
items:
$ref: '#/components/schemas/JobRow'
type: array
title: Jobs
matched_count:
anyOf:
- type: integer
- type: 'null'
title: Matched Count
description: 'List mode only: how many input entries matched a Sumble job.'
total:
type: integer
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
- jobs
- total
title: EnrichJobsResponse
JobsFilter:
properties:
organization_ids:
anyOf:
- items:
type: integer
type: array
maxItems: 1000
minItems: 1
- type: 'null'
title: Organization Ids
description: Sumble organization ids to scope the search to. Unknown ids simply match no jobs.
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 jobs returned (technologies, technology categories, job functions, countries, hiring period, ...).
additionalProperties: false
type: object
title: JobsFilter
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
app__schemas__paid_api__jobs__LookupTitlesResponse__JobFunction:
properties:
id:
type: integer
title: Id
slug:
type: string
title: Slug
name:
type: string
title: Name
type: object
required:
- id
- slug
- name
title: JobFunction
JobRelatedPeopleSelection:
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 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: []
limit:
type: integer
maximum: 25.0
minimum: 1.0
title: Limit
description: Maximum related people returned per job.
default: 5
job_levels:
items:
type: string
type: array
title: Job Levels
description: Only return related people whose job level is one of these (by name, e.g. 'Director', 'VP'); matching is OR across the list. When provided, this replaces the default seniority filter. When empty (the default), only likely hiring managers are returned — people at Manager level or above, and more senior than the role.
default: []
job_functions:
items:
type: string
type: array
title: Job Functions
description: Only return related people whose primary job function is one of these (by name, e.g. 'Engineering') or a descendant of one; matching is OR across the list and all descendants. Combined with `job_levels` as AND. Empty (the default) applies no job function filter.
default: []
sort_order:
type: string
enum:
- score
- level
title: Sort Order
description: 'How related people are ranked: ''score'' (similarity score, the default; ties broken by seniority) or ''level'' (seniority; ties broken by score).'
default: score
sort_direction:
type: string
enum:
- desc
- asc
title: Sort Direction
description: Direction for `sort_order`. The default 'desc' puts the highest score / most senior people first.
default: desc
additionalProperties: false
type: object
title: JobRelatedPeopleSelection
app__schemas__paid_api__jobs__LookupTitlesResponse__LookupResult:
properties:
input:
type: string
title: Input
job_function:
anyOf:
- $ref: '#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__JobFunction'
- type: 'null'
job_level:
anyOf:
- $ref: '#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__JobLevel'
- type: 'null'
type: object
required:
- input
- job_function
- job_level
title: LookupResult
PersonTechnology:
properties:
name:
type: string
title: Name
slug:
type: string
title: Slug
type: object
required:
- name
- slug
title: PersonTechnology
EnrichJobsRequest:
properties:
jobs:
anyOf:
- items:
$ref: '#/components/schemas/JobInput'
type: array
maxItems: 1000
minItems: 1
- type: 'null'
title: Jobs
description: List of jobs to enrich by id. One result row per entry, in input order. Mutually exclusive with `filter`.
filter:
anyOf:
- $ref: '#/components/schemas/JobsFilter'
- type: 'null'
description: Query selecting the jobs to return. Mutually exclusive with `jobs`.
select:
$ref: '#/components/schemas/JobsSelect'
description: Dictates exactly which attributes are returned.
limit:
type: integer
maximum: 200.0
minimum: 1.0
title: Limit
description: Maximum number of jobs to return (filter mode only; ignored when `jobs` 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 `jobs` is provided).
default: 0
additionalProperties: false
type: object
required:
- select
title: EnrichJobsRequest
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:
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sumble/refs/heads/main/openapi/sumble-jobs-api-openapi.yml