Endpoint

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

Person Identify API Access and Billing

You can access the Person Identify API through our self-signup dashboard

When the API finds a matching person, it returns up to 20 profiles sorted by match score along with an HTTP response code of 200. When it doesn't find a matching person, it returns an HTTP response code of 404. We charge per 200 & 404.

🚧
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 Name	Required	Description	Default	Example
`name`	No*	The person's full name (at least the first and the last.)		Jennifer C. Jackson
`first_name`	No*	The person's first name.		Jennifer
`last_name`	No*	The person's last name.		Jackson
`middle_name`	No	The person's middle name.		Cassandra
`location`	No*	The location in which a person lives, which can be anything from a street address to a country name.		Medford, OR USA
`street_address`	No*	The street address at which the person lives.		1234 Main Street
`locality`	No*	The locality in which the person lives.		Boise
`region`	No*	The state or region in which the person lives.		Idaho
`country`	No	The country in which the person lives.		United States
`postal_code`	No*	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
`company`	No*	The name, website or social URL of a company where the person has worked.		Amazon Web Services
`school`	No*	The name, website or social URL of a university or college that the person has attended.		university of iowa
`phone`	No*	A phone number the person has used. Input must begin with`+[country code]` for a match to be returned.		+1 555-234-1234
`email`	No*	The email that the person has used.		[email protected]
`email_hash`	No*	The sha256 or md5 email hash.		e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
`profile`	No*	The social profile that the person has used (see the list of available social profiles).		`https://linkedin.com/in/seanthorne`
`lid`	No*	The LinkedIn numerical ID		145991517
`birth_date`	No	The person's birth date: either a year or a full birth date.		35339
`titlecase`	No	The 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.	`false`	`true`
`pretty`	No	Whether the output should have human-readable indentation.	`false`	`true`
`api_key`	No*	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_matched`	No	If 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.	`false`	`true`

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 Name	Type	Description
`status`	`Integer`	The API response code.
`matches`	`Array [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_score`	`Integer`	An 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.data`	`Array [Object]`	The field attributes associated with this profile. For a list of fields, see the Person Schema.
`matches.matched_on`	`Array [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.