POST/v2/live/discover/people/advanced/translate

Translate an advanced discover request to v3

Rewrites an advanced discover request as the equivalent v3 discover request, the same rewrite the advanced search runs internally, and reports anything the v3 endpoint would reject. Does not perform a search or consume credits.

Version: v2
Rate limit: Tier 2 · 10–100 rps by plan
Billing: Discover · Translate an advanced discover request to v3

Request body

companyobjectOptional
Filters for company index (firmographic data)
- aggkCompanyIdobjectOptional
  AggKnowledge Company ID filter
  AND
  Values that must ALL be present (AND logic)
  OR
  15017574
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- companyFilterenum CompanyFilterTypeOptional
  Company filter mode: WORK_EXPERIENCE (default) or RELATIONSHIP
- companyNameobjectOptional
  Company name filter (supports partial/phrase matching). Bounded by the total number of words rather than by the number of values, so one long name costs as much as several short ones; a filter too large to evaluate is rejected with a 400
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- companyTypeobjectOptional
  Company type filter
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- companyWebsiteobjectOptional
  Company website filter
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- countryobjectOptional
  Company country
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- employeeCountRangeobjectOptional
  Employee count range filter
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- fundingRoundCountobjectOptional
  Range on the number of funding rounds the company has participated in
  - maxinteger (int32)Optional
    Maximum value (inclusive)
  - mininteger (int32)Optional
    Minimum value (inclusive)
- fundingTotalobjectOptional
  Range on the total funding raised and publicly disclosed, in USD
  - maxinteger (int64)Optional
    Maximum value (inclusive)
  - mininteger (int64)Optional
    Minimum value (inclusive)
- industryobjectOptional
  Industry filter
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- latestFundingAmountobjectOptional
  Range on the amount of the latest funding round. Companies with no known amount never match
  - maxinteger (int64)Optional
    Maximum value (inclusive)
  - mininteger (int64)Optional
    Minimum value (inclusive)
- latestFundingDateobjectOptional
  Latest funding date range
  - gtestringOptional
    Greater than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
  - ltestringOptional
    Less than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
- latestFundingStageobjectOptional
  Stage of the company's latest funding round
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- localityobjectOptional
  Company locality
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- primaryExchangeobjectOptional
  Company's primary stock exchange
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- primaryTickerobjectOptional
  Company's primary stock ticker
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- regionobjectOptional
  Company region
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- relationshipTypeenum RelationshipTypeOptional
  Relationship type filter (only used when companyFilter=RELATIONSHIP)
- revenueRangeInferredobjectOptional
  Revenue range inferred filter
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
cursorstringOptional
Pagination cursor from previous response for fetching next page of results
limitinteger (int32)Optional
Maximum number of results to return per page (default: 1000, max: 1000)
metadataobjectOptional
Optional metadata to associate with the request. Will be returned in the response.
{}
personobjectOptional
Filters for person attributes (location)
vendorgraphicsobjectOptional
Filters for vendorgraphics index (products and categories)
workExperienceobjectOptional
Filters for work experience index (job titles, roles, etc.)
- currentStartDateAtCompanyobjectOptional
  Date range filter for when a person started their current stint at the company
  - gtestringOptional
    Greater than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
  - ltestringOptional
    Less than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
- endDateobjectOptional
  End date range filter for work experiences
  - gtestringOptional
    Greater than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
  - ltestringOptional
    Less than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
- jobTitleobjectOptional
  Job title filter. Bounded by the total number of words across 'and', 'or' and 'not' rather than by the number of values, so one long title costs as much as several short ones; a filter too large to evaluate is rejected with a 400
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- originalStartDateAtCompanyobjectOptional
  Date range filter for when a person originally started at the company
  - gtestringOptional
    Greater than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
  - ltestringOptional
    Less than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
- personFilterenum PersonFilterOptional
  Person employment filter (CURRENT or PAST_NOT_CURRENT)
- roleobjectOptional
  Person's role at the company
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- seniorityobjectOptional
  Person's seniority at the company
  AND
  Values that must ALL be present (AND logic)
  OR
  vpcxo
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
- startDateobjectOptional
  Start date range filter for work experiences
  - gtestringOptional
    Greater than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
  - ltestringOptional
    Less than or equal to date (YYYY, YYYY-MM, or YYYY-MM-DD)
- subroleobjectOptional
  Person's subrole at the company
  AND
  Values that must ALL be present (AND logic)
  OR
  Values where at least ONE must be present (OR logic)
  NOT
  Values that must NOT be present (NOT logic)
groupingobjectOptional
Result diversity controls

Headers: x-api-key Required · API key for authentication

Response

metadataobject
Caller-supplied metadata echoed back from the request.
requestobject
The v3 discover request equivalent to the submitted request, ready to POST to /v3/{environment}/discover/people. The cursor becomes pagination.page and the limit pagination.size
warningsobject[]
Reasons /v3/{environment}/discover/people would reject the translated request, one per offending value. Empty when it can be sent as-is

Status codes

Response

Example

{
  "metadata": {},
  "request": {
    "metadata": {},
    "or": [
      {
        "company": {
          "aggkCompanyId": {
            "or": [
              "15017574"
            ]
          },
          "expansion": {
            "includeCompetitors": false,
            "includeParents": false,
            "includeSubsidiaries": false,
            "relationships": {
              "type": "VENDOR"
            }
          }
        },
        "workExperience": {
          "employmentStatus": "CURRENT",
          "seniority": {
            "or": [
              "vp",
              "cxo"
            ]
          }
        }
      }
    ],
    "pagination": {
      "page": 0,
      "size": 100
    }
  },
  "warnings": []
}