POST/v3/live/discover/people

Discover people

Returns persons matching complex criteria with and/or/not semantics organized by index (vendorgraphics, company, workExperience). Results are paginated via the request's pagination object (page and size); size defaults to 1000 and is capped at 1000, and no more than 5000 total results can be paged through.

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

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
    • pageinteger (int32)Optional
      0-indexed page number (default 0). (page + 1) * size must not exceed 5,000
    • sizeinteger (int32)Optional
      Results per page (default 1,000, maximum 1,000)
Headers
x-api-key Required · API key for authentication

Response

  • dataobject[]
    List of persons matching the search criteria
    • currentPositionsobject[]
      Every position the person currently holds, whether or not it matched the search
    • firstNamestring
      Person first name
    • idstring
      AggKnowledge Person ID. Pass it to Enrich as personId
    • lastNamestring
      Person last name
    • socialProfilestring
      Normalized professional social profile URL. Absent when the person has none on file.
    • matchingPositionsobject[]
      Every work experience of this person that satisfies the search, capped at 10. The first is the one the person ranked on, and the one a description snippet in matchedSnippets quotes; the rest follow most recent first. Under grouping.maxResultsPerCompany only the ranked one is returned
    • matchingProductobject
      The product behind a vendorgraphics match, with its detection window at the matched company. Always present: without a vendorgraphics filter productName is empty and the other fields are null
    • personCountrystring
      Person's country
    • personLocalitystring
      Person's locality (city)
    • personRegionstring
      Person's region (state)
    • matchedFilterGroupsstring[]
      Names of the filter groups satisfied by the work experience this person ranked on. An unnamed group is reported as group_<index>, its 0-based position in 'or'. A group the person satisfies only through a different work experience is not listed
    • matchedSnippetsobject[]
      The prose that satisfied the keywords filter, as highlighted fragments of the matched work experience's description and of the person's bio. This is the evidence behind the match: without it a keyword search returns a name and a job title with no indication of why the person was returned. Empty when the request carried no keywords filter, and when the match came from a field other than description or bio -- a title or company name match is already visible in matchingPositions
  • isRetryableboolean
    When isSuccess is false, whether sending the same input again could succeed. Always true when isSuccess is true.
  • 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.
  • metadataobject
    Caller-supplied metadata echoed back from the request.
  • estimatedCountinteger (int64)
    Estimated total number of matching results, saturating at 5000. Absent when grouping.maxResultsPerCompany is set, and when nothing matched. For an uncapped population size, call the count endpoint.
  • 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.
  • warningsstring[]
    Non-fatal warnings about the search, such as a detection window that was not enforced or a company.keywords filter that matched more than 10,000 companies

Status codes