# 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 /v6/people/find > Find people at an organization ```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":{"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":{"/v6/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 /v6/people/find-related-people > Find people related to a person ```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":{"FindPersonRelatedPeopleRequest":{"properties":{"person_id":{"type":"integer","minimum":1,"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":{"/v6/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 and/or phone) by their Sumble person ID. Choose which contact types to fetch with the `include_email` and `include_phone` flags. At least one must be `true` — requests with both set to `false` are rejected. Email and phone are billed independently: * A type is charged only when your account reveals it for that person for the first time. * If your account has already revealed that contact type for the person, subsequent requests for the same type return the previously revealed value at no additional credit cost. * If a type is requested but no value is available, no credits are charged for that type. ### Credit cost * **Email**: 10 credits the first time your account reveals an email for a given person. * **Phone**: 80 credits the first time your account reveals a phone for a given person. * No charge if your account has already revealed that contact type for the person, or if no contact info is found. ## POST /v6/people/enrich > Enrich a person with contact information ```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":{"EnrichPersonRequest":{"properties":{"person_id":{"type":"integer","minimum":1,"title":"Person Id","description":"Person ID to enrich with contact information"},"include_email":{"type":"boolean","title":"Include Email","description":"Whether to fetch the person's email address","default":false},"include_phone":{"type":"boolean","title":"Include Phone","description":"Whether to fetch the person's phone number","default":false}},"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/app__schemas__paid_api__enrich_person__ProfileContactInfo"},{"type":"null"}]},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["id","credits_used","credits_remaining","url","linkedin_url","contact_info","cached"],"title":"EnrichPersonResponse"},"app__schemas__paid_api__enrich_person__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":{"/v6/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"}}}}}}}}} ``` --- # Agent Instructions: 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/people.md?ask= ``` 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.