Discover

Rewrite the request body and update your response parsing. Filters, vocabularies, and results mean the same thing; a v2 Advanced request is translated into the v3 model and answered by the same query engine. But both wire shapes differ, so a v2 body POSTed to /v3/discover/people is rejected, and a v2 response parser will miss the matched role and misread IDs. Map both with the tables below, or see How Discover Works, where every example is shown on both versions. To convert a request you already have, translate it at the end of this page.

Status: Request and response shapes change

Request#

	v2 Advanced	v3
Body shape	one filter block at the top level	`or`: list of named filter groups (a single group is the direct equivalent)
Employment	`workExperience.personFilter`	`workExperience.employmentStatus`
Person location	`person.personCountry` / `personRegion` / `personLocality`	`person.country` / `region` / `locality`
Detection window	`vendorgraphics.filterByDetectionPeriod` + `detectionPeriodBuffer`	`vendorgraphics.detectionWindow.enforce` + `buffer`
Pagination	`cursor` + `limit`	`pagination.page` + `size`
Relationship search	`company.companyFilter: RELATIONSHIP` + `relationshipType`	`company.expansion.relationships.type`, with `CUSTOMER` and `VENDOR` swapped (see below)

Watch out: relationship types are inverted. v2’s relationshipType names what the search returns; v3’s relationships.type names the role the seed companies play. v2 CUSTOMER (return the seeds’ customers) is v3 VENDOR; v2 VENDOR is v3 CUSTOMER; PARTNER is unchanged. v2 defaulted to CUSTOMER when relationshipType was omitted, so a v2 request without it becomes v3 VENDOR. Copying the value across unchanged returns the opposite side of the relationship.

Watch out: counts mean different things. v2’s /discover/people/advanced/count counts matching work experiences, so someone holding two matching roles is counted twice. v3’s /discover/people/count counts distinct people, matching what the search returns, so expect a v3 count at or below the v2 figure for the same filters. v3 counts are exact up to 40,000 people and estimated above that, flagged by isApproximate.

The validate → count → discover loop survives the move. Both versions expose the free count and validate operations.
v3 adds what v2 cannot express: filter-group unions (“current employees or recent leavers” in one call, with matchedFilterGroups on every result), company.expansion for the subsidiaries, parents, and related companies of your seed accounts, group-level keywords over titles, descriptions, and bios, and workExperience.activeWithin for recency.
Expect Discover volume to grow. It is the designated replacement for deprecated Person Search.

Response#

	v2 Advanced	v3
Matched role	`data.matchingCompany`: one object	`data.matchingPositions`: an array of up to 10, the ranked role first
Social profile	`data.linkedinUrl`	`data.socialProfile` (nullable)
IDs	`data.id`, `currentPositions.aggkCompanyId`, and `matchingProduct.aggkProductId` are integers	The same fields are strings
Person location codes	`data.personCountryCode` / `personRegionCode`	Removed. `personCountry` / `personRegion` / `personLocality` remain
Next page	`nextCursor`	Removed. Request `page + 1` until a page comes back short
New in v3		`data.matchedFilterGroups`, `data.matchedSnippets`, and `warnings`

Watch out: read IDs as strings. v3 returns every ID as a JSON string. Store and compare them as strings; converting them to a number silently corrupts values above 2⁵³.

Discover Basic#

v2 Discover Basic (/discover/people, /count, /validate) is deprecated and has no v3 counterpart. Move it to v3 Discover, which takes the Advanced shape above. Each flat Basic field becomes a filter inside a single or group:

v2 Basic	v3
List fields (`aggkCompanyId`, `industry`, `role`, `jobTitle`, …)	`{ "or": [...] }` on the same field in its block (`company`, `workExperience`, or `vendorgraphics`)
Single-value company location (`country`, `region`, `locality`)	`company.country` / `region` / `locality` as a one-item `or`
`personCountry` / `personRegion` / `personLocality`	`person.country` / `region` / `locality` as a one-item `or`
`earliestStartDate` / `latestStartDate` (and the `EndDate`, `CurrentStartDateAtCompany`, and `OriginalStartDateAtCompany` pairs)	`workExperience.startDate.gte` / `lte` (and the matching range on each field)
`personFilter`	`workExperience.employmentStatus`
`cursor` + `limit`	`pagination.page` + `size`

Basic returns the matched role flat on each result (company, jobTitle, role, startDate, …); v3 returns it in data.matchingPositions, with the other response changes above.

Translate a request#

Pick an example or paste your own v2 Advanced body to get its v3 equivalent. The translation is the one the API already runs: every v2 Advanced search is rewritten into this shape before it is answered, so the result behaves the same on v3. The cursor becomes pagination.page and the limit pagination.size. To translate in bulk, call POST /v2/{environment}/discover/people/advanced/translate, which is free.

v2 Advanced request body

The v3 body appears here, translated by the same code that runs your v2 searches today.