Skip to main content

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 API lets you query Descovo’s database of over 847 million professional profiles using filters like job title, geography, years of experience, and current employer. You can page through results, apply exclusion lists to suppress known contacts, and optionally retrieve expanded education and work history — all in a single POST request.

​
Endpoint

POST /v1/people-search
Authentication uses your API key passed directly in the request body. Credits are charged per profile returned.

​
Request parameters

​
apiKey
string
required
Your Descovo API key.
​
searchParams
object
required
People filters. See key fields below.
​
pageSize
number
default:"25"
Number of profiles to return per page. Maximum is 1000.
​
cursor
string
Opaque pagination cursor. Pass null for the first page, then the nextCursor value from each response.
​
currentCompanies
object[]
Restrict results to people who currently work at these companies. Each entry can include domain, linkedinSlugOrURL, name, or linkedinOrgID — supply any combination.
​
prospectExclusionListIDs
string[]
IDs of exclusion lists used to suppress specific people from results.
​
companyExclusionListIDs
string[]
IDs of exclusion lists used to suppress people at certain companies.

​
Key searchParams fields

​
searchParams.jobTitleV2
object
Include and exclude job titles using OR logic within each list.
{
  "included": ["VP Engineering", "Head of Engineering"],
  "excluded": ["Recruiter", "HR"]
}
​
searchParams.country3LetterCode
string[]
Filter by country using ISO 3-letter codes, e.g. "USA", "CAN", "GBR".
​
searchParams.yearsOfExperience
object
Filter by total years of professional experience.
{ "min": 5, "max": 15 }
​
searchParams.tags
object
Filter by structured prospect tags using anyOf, allOf, or noneOf logic.
​
searchParams.education
object
Filter by degree type or institution.
​
searchParams.getDetailedEducation
boolean
default:"false"
When true, each profile includes expanded degree and school information. Increases response latency and payload size.
​
searchParams.getDetailedWorkExperience
boolean
default:"false"
When true, each profile includes full work history with company details. Increases response latency and payload size.

​
Response fields

​
output.data
object[]
Array of matched profiles.
​
output.nextCursor
string | null
Pass this value as cursor in your next request to retrieve the following page. null when there are no more results.
​
chargeInfo.creditsCharged
number
Number of credits charged for this response.

​
Example: find VPs of Engineering at US AI companies

The request below finds up to 25 VP Engineering profiles in the United States at companies tagged with AI or machine learning. 
{
  "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": []
}

​
Job title filter syntax

The jobTitleV2 filter uses include/exclude logic. Titles in included are matched with OR logic — a profile only needs to match one. Titles in excluded are always suppressed. 
{
  "jobTitleV2": {
    "included": [
      "Senior Software Engineer",
      "Staff Software Engineer",
      "Principal Engineer"
    ],
    "excluded": [
      "Manager",
      "Director",
      "VP",
      "Head"
    ]
  }
}
Keep your included list small and intent-driven. Broad lists with dozens of titles produce noisier results and charge more credits.

​
Pagination

People Search uses cursor-based pagination. Keep searchParams identical between pages — only update the cursor value. 
{
  "apiKey": "sk_live_xxx",
  "searchParams": { "...": "your filters" },
  "pageSize": 50,
  "cursor": null
}
Stop paginating when nextCursor is null.
The default page size is 25 and the maximum is 1000. For large-scale prospecting, consider the audience workflow instead of paging through thousands of results inline.

​
Credit costs

Credits are charged per profile returned. Each profile counts as one getPersonFromDb unit. More profiles returned means more credits consumed.
  • For small explorations (up to ~100 profiles), you can search directly.
  • For large or repeated searches, use the audience workflow to manage enrichment and exports at scale.

​
Filtering by current company

Populate currentCompanies when you want people who work at specific employers. You can identify each company by any combination of identifiers — Descovo resolves them automatically: 
{
  "currentCompanies": [
    {
      "domain": "example.com",
      "linkedinSlugOrURL": "https://www.linkedin.com/company/example/",
      "name": "Example Inc",
      "linkedinOrgID": "1441"
    }
  ]
}