Release NotesDocumentationAPI ReferenceSupportAPI StatusRoadmap
Start Building

Reference - Person Identify API

Reference information for the Person Identify API

Suggest Edits

Endpoint

The endpoint for the Person Identify API is https://api.peopledatalabs.com/v5/person/identify.

Person Identify API Access and Billing

The Person Identify API is currently available only to enterprise customers. In order to request access to this endpoint, please speak to our sales team.

🚧

Warning: Credit Usage

Each call that you make to the Person Identify API will consume one credit, regardless of the number of profiles that the API returns.

This behavior differs from that of our other APIs, which consume one credit for each profile that they return.

Rate Limiting

The default rate limit for all customers is 10 calls per minute.

Input Parameters

📘

For More Details, See Person Identify API - Input Parameters

You can also click on the individual parameter names in the table below to view more information on them.

Parameter NameRequiredDescriptionDefaultExample
nameNo*The person's full name (at least the first and the last.)Jennifer C. Jackson
first_nameNo*The person's first name.Jennifer
last_nameNo*The person's last name.Jackson
middle_nameNoThe person's middle name.Cassandra
locationNo*The location in which a person lives, which can be anything from a street address to a country name.Medford, OR USA
street_addressNo*The street address at which the person lives.1234 Main Street
localityNo*The locality in which the person lives.Boise
regionNo*The state or region in which the person lives.Idaho
countryNoThe country in which the person lives.United States
postal_codeNo*The postal code in which the person lives. If there is no value for country, we assume that the postal code is in the US.83701
companyNo*The name, website or social URL of a company where the person has worked.Amazon Web Services
schoolNo*The name, website or social URL of a university or college that the person has attended.university of iowa
phoneNo*The phone number that the person has used, in any format.+1 555-234-1234
emailNo*The email that the person has used.[email protected]
email_hashNo*The sha256 or md5 email hash.e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
profileNo*The social profile that the person has used (see the list of available social profiles).https://linkedin.com/in/seanthorne
lidNo*The LinkedIn numerical ID145991517
birth_dateNoThe person's birth date: either a year or a full birth date.35339
titlecaseNoThe API returns all text in the data object of responses as lowercase by default. Setting titlecase to true will titlecase the person data in 200 responses.falsetrue
prettyNoWhether the output should have human-readable indentation.falsetrue
api_keyNo*Your secret API key.

While we do not require this as part of the request parameters, if you do not provide it here, then you must provide it using an alternative means, such as in the headers using the x-api-key field. For more information, see the Authentication page.		None
include_if_matchedNoIf set to true, the output will contain the matches.matched_on field which will list the fields in each profile that matched the input query.falsetrue

Note (*): While we don't require any of these parameters individually, you must provide a sufficient combination of them as inputs. For more details, see the minimum required inputs.

Output Response

Response Fields

📘

For More Details, See Person Identify API - Output Response

You can also click on the individual parameter names in the table below to view more information on them.

Field NameTypeDescription
statusIntegerThe API response code.
matchesArray [Object]A list of up to 20 profiles matching the input criteria from the API request. The API only returns profiles with a match_score greater than 5 (out of 100.)
matches.match_scoreIntegerAn integer between 1-99 drawn from a probability-like distribution representing the matching strength between a profile and the input criteria. In other words, the probability that this record is the record that you are looking for based on your query.
matches.dataArray [Object]The field attributes associated with this profile. For a list of fields, see the Person Schema.
matches.matched_onArray [String]A list of data fields that the API matched for this profile. The API only returns this if you set the include_if_matched input parameter to true.

Response Data Structure

The response from the Person Identify API will be in this format:

{
  "status": 200,
  "matches": [
    {
      "data": {
        ...
      },
      "match_score": 92,
      "matched_on": [
        "company",
        "name"
      ]
    },
    {
      "data": {
        ...
      },
      "match_score": 5,
      "matched_on": [
        "name"
      ]
    },
    ...
  ]
}

Errors

If the request encounters an error, it will instead return an Error Response in the format described in Errors.

Updated 4 months ago