Documentation Index Fetch the complete documentation index at: https://docs.descovo.com/llms.txt
Use this file to discover all available pages before exploring further.
The people search endpoint lets you find professionals matching a combination of filters: job titles, countries, years of experience, industry tags, education, and current employer. Results are returned as enriched profile objects with pagination support. Credits are charged per profile the API returns — not per request — so narrower filters keep costs predictable.
Endpoint: POST https://api.descovo.com/v1/people-searchAuth: apiKey in the request bodyRequest parameters People filter criteria. All sub-fields are optional; combine them to narrow results. Show searchParams properties
Include or exclude profiles by job title. Titles in included are matched with logical OR; profiles matching any title in excluded are removed. { "included" : [ "VP Engineering" , "Head of Engineering" ], "excluded" : [ "Recruiter" , "HR" ] }
searchParams.country3LetterCode
ISO 3166-1 alpha-3 country codes to filter by profile location. Examples: "USA", "CAN", "GBR".
searchParams.yearsOfExperience
Filter by total years of professional experience. searchParams.yearsOfExperience.min
Minimum years of experience (inclusive).
searchParams.yearsOfExperience.max
Maximum years of experience (inclusive).
Filter profiles by structured industry or topic tags. Accepts anyOf (at least one tag matches) or allOf (all tags must match). { "anyOf" : [ "artificial-intelligence" , "machine-learning" ] }
Filter by degree level or institution. Supports degree type and school name criteria.
searchParams.getDetailedEducation
When true, each returned profile includes expanded degree and institution details. Increases response size and latency.
searchParams.getDetailedWorkExperience
When true, each returned profile includes a full work history with company details. Increases response size and latency.
Restrict results to profiles who currently work at specific companies. Each entry can include any combination of identifiers — Descovo will resolve them to robust internal IDs. Show currentCompanies item properties
currentCompanies[].domain
Company website domain, e.g. "example.com".
currentCompanies[].linkedinSlugOrURL
LinkedIn company slug or full URL, e.g. "https://www.linkedin.com/company/example/".
currentCompanies[].linkedinOrgID
LinkedIn organization ID, e.g. "1441".
IDs of saved exclusion lists. Profiles on these lists are removed from results.
IDs of saved company exclusion lists. Profiles who work at excluded companies are removed from results.
Number of profiles to return per page. Maximum is 1000.
Pagination cursor from the previous response’s nextCursor. Omit or pass null for the first page.
Response fields Array of profile objects matching your filters. Profile’s reported location, including city and country_code.
output.data[].current_company
Current employer with name, linkedin_slug, and domain.
Languages the profile lists, each with name and proficiency_name.
output.data[].detailed_education
Expanded education history. Present when getDetailedEducation is true.
output.data[].detailed_work_experiences
Expanded work history. Present when getDetailedWorkExperience is true.
Pass this value as cursor in your next request to fetch the next page. null when there are no more results.
Credit charge details for this request. charged-now for people search results.
chargeInfo.creditsCharged
Total credits deducted — one credit per profile returned.
Example Request: find VP Engineering profiles at US AI companies { "apiKey" : "sk_live_xxx" , "searchParams" : { "jobTitleV2" : { "included" : [ "VP Engineering" , "VP of Engineering" , "Head of Engineering" ], "excluded" : [ "Recruiter" , "HR" ] }, "country3LetterCode" : [ "USA" ], "yearsOfExperience" : { "min" : 5 }, "tags" : { "anyOf" : [ "artificial-intelligence" , "machine-learning" ] } }, "pageSize" : 25 , "cursor" : null , "currentCompanies" : [], "prospectExclusionListIDs" : [], "companyExclusionListIDs" : [] }
Response: { "output" : { "data" : [ { "first_name" : "Alice" , "last_name" : "Smith" , "title" : "VP Engineering" , "headline" : "VP Engineering at Descovo AI" , "location" : { "city" : "San Francisco" , "country_code" : "US" }, "current_company" : { "name" : "Descovo AI" , "linkedin_slug" : "descovo-ai" , "domain" : "descovo.ai" }, "languages" : [ { "name" : "English" , "proficiency_name" : "Native or bilingual proficiency" } ], "detailed_education" : null , "detailed_work_experiences" : null } ], "nextCursor" : "eyJsYXN0X3NvcnRfa2V5IjoiYWJjMTIzIn0" }, "chargeInfo" : { "method" : "charged-now" , "creditsCharged" : 25 } }
Notes For large-scale prospecting — thousands of profiles — consider using an audience workflow instead of paginating through raw search results. Audiences let you save the result set and run enrichment and exports without holding everything in memory.
Credits are charged per profile returned. Use a small pageSize while validating your filters to avoid unnecessary charges.
Keep searchParams identical between pages; only change cursor. Changing filters mid-pagination produces inconsistent results.
See Pagination for the full cursor-based pagination model.
See Credits for per-operation costs.
