POST/v2/live/person/match

Match

Accepts a person match request with required full name and optional multiple companies, domains, and emails. Returns possible matches limited to 250 results.

Version
v2Open on v3
Rate limit
Tier 3 · 10–200 rps by plan
Billing
Person Search · Match

Request body

  • companyDomainsstring[]Optional
    Current or former employer domains of the person.
    henryschein.comaggknowledge.ai
    Enter adds a value · Backspace on empty removes the last
  • companyNamesstring[]Optional
    Current or former employer names of the person; a person matches on any one of them. Each name is resolved to an AggKnowledge company, so typos, aliases and legal suffixes all match. Each name is also matched against the employer recorded on the work experience itself, which reaches employers we hold no company record for. At most 10 values.
    henry scheinaggknowledge
    Enter adds a value · Backspace on empty removes the last
  • emailAddressesstring[]Optional
    Current or former email addresses of the person.
    dan.entrup@example.comd.entrup@example.org
    Enter adds a value · Backspace on empty removes the last
  • fullNamestringOptional
    The person's full name. Either fullName or linkedinUrl must be provided. A name too long to evaluate is rejected with a 400.
  • jobTitlesstring[]Optional
    Job titles held by the person; a person matches on any one of them. When combined with a company criterion, a single work experience must satisfy both. Bounded by the total number of words rather than by the number of titles, so one long title costs as much as several short ones; a list too large to evaluate is rejected with a 400.
    co-founderchief technology officer
    Enter adds a value · Backspace on empty removes the last
  • linkedinUrlstringOptional
    LinkedIn URL of the person. Either fullName or linkedinUrl must be provided.
  • locationCitystringOptional
    City where the person is located.
  • locationCountrystringOptional
    Country where the person is located.
  • locationStateOrProvincestringOptional
    State or province where the person is located.
  • aggkCompanyIdsinteger (int64)[]Optional
    AggKnowledge company IDs of current or former employers of the person.
  • metadataobjectOptional
    Optional metadata to associate with the request. Will be returned in the response.
Headers
x-api-key Required · API key for authentication

Response

  • resultsobject[]
    People matched to the request
    • fullNamestring
      The person's full name
    • hasEmailboolean
    • isEmailMatchboolean
    • matchingExperiencesobject[]
      The work experiences that satisfied the match criteria. A person can match on more than one — a promotion, a second stint, or two of the supplied companies each produce an entry. Unlike previousEmployerNames, which covers every experience on file, this covers only the matching ones. Empty unless the request supplied a company or job title criterion: name, email, profile URL and location criteria hold on every experience the person has, so there is no subset to report.
    • linkedinUsernamestring
      The person's profile username
    • locationCitystring
    • locationCountrystring
    • locationCountryCodestring
      ISO 3166-1 alpha-2 code of locationCountry
    • locationStateOrProvincestring
    • personIdinteger (int64)
    • previousEmployerDomainsstring[]
    • previousEmployerNamesstring[]
    • aggkCompanyIdsinteger (int64)[]
    • scoreinteger
      How strong this match is, from 0 to 100. Results are ordered by score descending, so callers can auto-accept the top hit or review the top N. The score is computed from the criteria in matchedCriteria rather than from text relevance, so it means the same thing across requests and is not affected by how common the supplied name is. It is an ordinal measure of corroborating evidence, not a probability, and the weights behind it will be re-tuned; a rule that must be stable should be written against matchedCriteria.
    • matchedCriteriaenum[] MatchCriterion
      Which criteria this person matched on, strongest first — the evidence the score is computed from. A name criterion is always present. Employer and location criteria appear only when the request supplied them.
  • metadataobject
    Caller-supplied metadata echoed back from the request.

Status codes