> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/core-data/jobs.md).

# Job posts

## Find, match, and enrich job posts

The single endpoint for working with job postings. Provide either a **list of job IDs** to resolve (list mode) or an **advanced query filter** (search mode), and compose exactly which attributes you get back. This replaces the previous `find`, job details, and `find-related-people` endpoints.

### Input

Provide exactly one of:

* **`jobs`** — a list of up to 1,000 jobs to resolve, each identified by its Sumble `job_id`. Covers the previous job details flow. Limited to 200 entries when requesting descriptions and 25 entries when requesting related people.
* **`filter`** — the jobs to return: `organization_ids` (up to 1,000), a saved `organization_list_id`, and/or an advanced `query` (technologies, technology categories, job functions, countries, hiring period, and more). A query on its own searches the whole corpus. Covers the previous `find` flow.

In filter mode, `limit` (default 10, max 200) and `offset` page through results.

### Composable response

The `select` block dictates exactly which attributes return — nothing is mandatory:

* **`attributes`** — a list of job attributes, or `"all"`. Available: `title`, `description` (the full posting text), `location`, `posted_date`, `organization`, and the extracted entities `technologies` (with a `used` flag distinguishing technologies the team uses from ones merely mentioned), `teams`, `job_functions`, `job_levels`, and `projects`. `job_id` and `sumble_url` are always included for free.
* **`related_people`** — the people most relevant to each job, typically hiring managers and team members at the organization. Choose which person attributes to return and a per-job `limit` (default 5, max 25). Available in both modes, for up to 25 jobs per request.

### Credit cost

Charged per matched job (list mode) or per returned job (search mode). Unmatched inputs are free.

Per job the cost is:

* **1 base credit**, plus:
* **1 credit per paid attribute** requested (`title` is free), plus
* **1 credit per related person** returned.

For example, returning 5 jobs with 3 paid attributes and 2 related people each costs `5 × (1 + 3 + 2) = 30` credits. The API checks affordability up front and returns HTTP `402` before doing any work you can't pay for.

## POST /v6/jobs

> Unified jobs endpoint

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"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,"minimum":1,"title":"Limit","description":"Maximum number of jobs to return (filter mode only; ignored when `jobs` is provided).","default":10},"offset":{"type":"integer","maximum":10000,"minimum":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"},"JobInput":{"properties":{"job_id":{"type":"integer","minimum":1,"title":"Job Id","description":"Job id on Sumble."}},"additionalProperties":false,"type":"object","required":["job_id"],"title":"JobInput"},"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},{"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"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"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"},"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,"minimum":1,"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"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"},"PersonTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"}},"type":"object","required":["name","slug"],"title":"PersonTechnology"},"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"},"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"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v6/jobs":{"post":{"tags":["jobs"],"summary":"Unified jobs endpoint","operationId":"enrich_jobs_unified__api_version__jobs_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichJobsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichJobsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sumble.com/api/core-data/jobs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.