# People

Find people at a specific organization. Results can be filtered by job function, job level, and technology skills.

When filtering by job function or job level, use the values shown in the Sumble web application (e.g., "Engineering", "Director").

## Credit cost

Each person returned costs 1 credit.

## POST /v5/people/find

> Find people at an organization

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"FindPeopleRequest":{"properties":{"organization":{"anyOf":[{"$ref":"#/components/schemas/OrganizationByDomain"},{"$ref":"#/components/schemas/OrganizationById"},{"$ref":"#/components/schemas/OrganizationBySlug"},{"$ref":"#/components/schemas/OrganizationByLinkedinUrl"}],"title":"Organization","description":"Organization to enrich"},"limit":{"type":"integer","maximum":250,"minimum":1,"title":"Limit","description":"Maximum number of people to return","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip","default":0},"filters":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__paid_api__find_people__FindPeopleRequest__Filters"},{"$ref":"#/components/schemas/Query"}],"title":"Filters","description":"Filters to apply to the people search. Can be either a Filters object or a Query object."}},"type":"object","required":["organization","filters"],"title":"FindPeopleRequest"},"OrganizationByDomain":{"properties":{"domain":{"type":"string","title":"Domain","description":"Company web domain"}},"type":"object","required":["domain"],"title":"OrganizationByDomain"},"OrganizationById":{"properties":{"id":{"type":"integer","title":"Id","description":"Organization Id on Sumble"}},"type":"object","required":["id"],"title":"OrganizationById"},"OrganizationBySlug":{"properties":{"slug":{"type":"string","title":"Slug","description":"Organization Slug on Sumble"}},"type":"object","required":["slug"],"title":"OrganizationBySlug"},"OrganizationByLinkedinUrl":{"properties":{"linkedin_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Linkedin Url","description":"Organization LinkedIn URL"}},"type":"object","required":["linkedin_url"],"title":"OrganizationByLinkedinUrl"},"app__schemas__paid_api__find_people__FindPeopleRequest__Filters":{"properties":{"job_functions":{"items":{"type":"string"},"type":"array","title":"Job Functions","description":"Job function to filter by (e.g. Engineer, Executive)","default":[]},"job_levels":{"items":{"type":"string"},"type":"array","title":"Job Levels","description":"Job level to filter by (e.g. Senior, Manager)","default":[]},"countries":{"items":{"type":"string"},"type":"array","title":"Countries","description":"Countries to filter by (e.g. US, CA)","default":[]},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Only consider data since this date. Format: YYYY-MM-DD"}},"type":"object","title":"Filters"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"FindPeopleResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization":{"$ref":"#/components/schemas/MatchedOrganization"},"people_count":{"type":"integer","title":"People Count"},"people_data_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"People Data Url"},"people":{"items":{"$ref":"#/components/schemas/PersonResult"},"type":"array","title":"People"}},"type":"object","required":["id","credits_used","credits_remaining","organization","people_count","people_data_url","people"],"title":"FindPeopleResponse"},"MatchedOrganization":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"domain":{"type":"string","title":"Domain"}},"type":"object","required":["id","slug","name","domain"],"title":"MatchedOrganization"},"PersonResult":{"properties":{"id":{"type":"integer","title":"Id"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Linkedin Url"},"name":{"type":"string","title":"Name"},"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"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"}},"type":"object","required":["id","url","linkedin_url","name","job_title","job_function","job_level","location","country","start_date","country_code"],"title":"PersonResult"},"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":{"/v5/people/find":{"post":{"tags":["people"],"summary":"Find people at an organization","operationId":"find_people__api_version__people_find_post","parameters":[{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPeopleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPeopleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Find Related People

Find people at the same organization who are related to a given person, based on shared features such as technologies, job functions, teams, and locations.

Each result includes a `direction` field indicating whether the person is `above` or `below` the source person in the organizational hierarchy.

### Credit cost

Each person returned costs 1 credit.

## POST /v5/people/find-related-people

> Find people related to a person

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"FindPersonRelatedPeopleRequest":{"properties":{"person_id":{"type":"integer","title":"Person Id","description":"Person ID to find related people for"},"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of people to return","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip","default":0}},"type":"object","required":["person_id"],"title":"FindPersonRelatedPeopleRequest"},"FindPersonRelatedPeopleResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"total":{"type":"integer","title":"Total"},"people":{"items":{"$ref":"#/components/schemas/RelatedPersonResult"},"type":"array","title":"People"},"source_data_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Source Data Url"}},"type":"object","required":["id","credits_used","credits_remaining","total","people","source_data_url"],"title":"FindPersonRelatedPeopleResponse"},"RelatedPersonResult":{"properties":{"id":{"type":"integer","title":"Id"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"linkedin_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Linkedin Url"},"name":{"type":"string","title":"Name"},"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"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"direction":{"type":"string","title":"Direction"}},"type":"object","required":["id","url","linkedin_url","name","job_title","job_function","job_level","location","country","start_date","country_code","direction"],"title":"RelatedPersonResult"},"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":{"/v5/people/find-related-people":{"post":{"tags":["people"],"summary":"Find people related to a person","operationId":"find_related_people__api_version__people_find_related_people_post","parameters":[{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPersonRelatedPeopleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPersonRelatedPeopleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Enrich Person

Enrich a person with contact information (email, phone) by their Sumble person ID.

If the person has already been enriched by your account, cached results are returned at no additional credit cost. If contact information is not available from the provider, no credits are charged.

### Credit cost

10 credits per successful enrichment. No charge if the result is cached or if no contact info is found.

## POST /v5/people/enrich

> Enrich a person with contact information

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v5"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"EnrichPersonRequest":{"properties":{"person_id":{"type":"integer","title":"Person Id","description":"Person ID to enrich with contact information"}},"type":"object","required":["person_id"],"title":"EnrichPersonRequest"},"EnrichPersonResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"contact_info":{"anyOf":[{"$ref":"#/components/schemas/ProfileContactInfo"},{"type":"null"}]},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["id","credits_used","credits_remaining","url","linkedin_url","contact_info","cached"],"title":"EnrichPersonResponse"},"ProfileContactInfo":{"properties":{"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["emails"],"title":"ProfileContactInfo"},"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":{"/v5/people/enrich":{"post":{"tags":["people"],"summary":"Enrich a person with contact information","operationId":"enrich_person__api_version__people_enrich_post","parameters":[{"name":"require_mcp","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Require Mcp"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPersonRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPersonResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```