POST/v2/live/discover/people/advanced/validate

Validate an advanced discover request

Validates all field values in an advanced discover request and returns detailed warnings for any invalid values (especially enums such as role, industry, seniority). It also flags a request too large to evaluate (QUERY_TOO_LARGE), which a search would refuse with a 400. Does not perform a search or consume credits.

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

Request body

companyobjectOptional
Filters for company index (firmographic data)
- aggkCompanyIdobjectOptional
  AggKnowledge Company ID filter
  OR
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  AND
  Values that must ALL be present (AND logic)
  OR
  software
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  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
groupingobjectOptional
Result diversity controls
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
  Backed by a single-valued field — more than one and value can never match.
  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
  Backed by a single-valued field — more than one and value can never match.
  AND
  Values that must ALL be present (AND logic)
  OR
  seniorcxo
  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
  Backed by a single-valued field — more than one and value can never match.
  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)

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

Response

isValidboolean
Whether all provided values are valid (true when warnings is empty)
metadataobject
Caller-supplied metadata echoed back from the request.
warningsobject[]
List of validation warnings, one per invalid field value

Status codes

Response

Example

{
  "isValid": true,
  "metadata": {},
  "warnings": [
    {
      "code": "I50",
      "field": "industry",
      "message": "Unrecognized industry value: 'softwares'",
      "validValues": [
        "computer software",
        "information technology and services",
        "financial services"
      ],
      "value": "softwares"
    }
  ]
}