POST/v3/live/discover/people/validate

Validate a discover people request

Validates all field values in a discover request and returns detailed warnings for any invalid values (especially enums such as role, industry, seniority), filters placed under the wrong entity, v2 field names that v3 renamed, and a v2-shaped body whose filters sit at the root instead of inside an 'or' group. It also flags a request too large to evaluate (QUERY_TOO_LARGE), which a search would refuse with a 400. Warnings about a filter group's contents name the group they came from. Does not perform a search or consume credits.

Version
v3
Rate limit
Tier 2 · 10–100 rps by plan
Billing
Discover · Validate a discover people request

Request body

  • metadataobjectOptional
    Optional metadata to associate with the request. Will be returned in the response.
  • groupingobjectOptional
    Result diversity controls
  • orobject[]Optional
    One or more filter groups. A person matches the request when they satisfy at least one group; within a group every filter is ANDed
    • companyobjectOptional
      Company firmographic filters for this group, applied to the employer on the matched work experience
    • keywordsobjectOptional
      Boolean keyword expression over this group's indexed prose. A node is either a leaf (phrase or term) or a branch (all, any, none) -- never both. Branch lists nest: each element is itself a keyword expression, so (a OR b) AND (c OR d) is an 'all' of two 'any' nodes. Note the two grains: description, title and companyName match per work experience, while bio is carried on every one of a person's documents and so matches per person -- an 'all' of two experience fields means the same role, and relaxes to the same person once one leaf targets the bio. 'none' is likewise per work experience for the experience fields: it removes the matching role, not the person.
    • namestringOptional
      Name for this group. Echoed in matchedFilterGroups on every result the group produced, and in validate warnings about the group
    • personobjectOptional
      Filters on the person rather than a work experience: where they live, which is not necessarily where their employer is, the people to exclude, and the schools they attended
    • vendorgraphicsobjectOptional
      Product usage filters: people at companies where a product, or any product in a category, was detected
    • workExperienceobjectOptional
      Work experience filters. Every work experience, company and keyword filter in a group must hold on the same work experience
  • paginationobjectOptional
    Page-based pagination controls
Headers
x-api-key Required · API key for authentication

Response

  • isValidboolean
    Whether all provided values are valid (true when warnings is empty)
  • warningsobject[]
    List of validation warnings, one per invalid field value
    • fieldstring
      Path to the field holding the invalid value, qualified by its filter group (e.g. 'or[0].workExperience.role')
    • groupstring
      Name of the filter group the warning came from, when the group supplied one. Absent for unnamed groups and for warnings about the request as a whole.
    • valuestring
      The invalid value that was provided. Absent for warnings that are not tied to a specific value (e.g. MUTUALLY_EXCLUSIVE_FIELDS).
    • messagestring
      Human-readable description of the validation problem
    • codestring
      Machine-readable warning code (e.g. 'INVALID_ENUM_VALUE', 'INVALID_DATE_FORMAT', 'MUTUALLY_EXCLUSIVE_FIELDS', 'MISPLACED_FIELD', 'RENAMED_FIELD', 'UNKNOWN_FIELD', 'DUPLICATE_KEYWORD', 'MISSING_FILTER_GROUP')
    • validValuesstring[]
      Valid values accepted for this field, when applicable
  • querySizeobject
    How much of the query size limit the request uses, present whether or not it fits. Null when the request could not be sized: it did not parse, or it has a malformed keywords expression, activeWithin or company.keywords to fix first, and QUERY_TOO_LARGE is not checked until it can be. company.keywords is also sized on its own against the companies it searches, so a QUERY_TOO_LARGE naming company.keywords can arrive with 'used' under 'limit'.
  • metadataobject
    Caller-supplied metadata echoed back from the request.
  • isSuccessboolean
    true when the request was answered with a result. false means no result was returned: check isRetryable, which is true when a data source failed or timed out and false when the input matched nothing.
  • isRetryableboolean
    When isSuccess is false, whether sending the same input again could succeed. Always true when isSuccess is true.
  • hasProblemsboolean
    Whether we hit a problem answering the request: the profile or company wasn't found, or a data source failed or timed out. Data may be missing or incomplete; problems, where the response has it, says which.

Status codes