Reference - Person Enrichment API
The Person Enrichment API provides a one-to-one person match, retrieving up-to-date information on a unique individual.
Endpoint
The endpoint for the Person Enrichment API is https://api.peopledatalabs.com/v5/person/enrich
.
Person Enrichment API Access and Billing
You can access the Person Enrichment API through our self-signup dashboard
When the API finds a matching person, it returns this person 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 match.
Requests
See Authentication and Requests sections to see all possible ways to input a request. We recommend using a JSON object to capture input parameters and will do so in the examples.
Rate Limiting
Our default limit for free customers is 100 per minute. Our default limit for paying customers is 1,000 per minute.
Note: To allow for more enrichments without putting too much strain on our system, you can use the Bulk Person Enrichment API to increase the number of enrichments per request, effectively increasing your rate limit by up to a hundred times.
Input Parameters
When querying the API in URL, you can add data points to a queried person as key/value pairs at the end of a v5
request string.
You can use the following parameters to specify information on a requested person. Adding more data points to a request increases the probability of a 200
response and will further increase the accuracy of the response's Likelihood Score.
All query parameters listed below are optional.
For more details, see Input Parameters - Person Enrichment API
You can also click on the individual parameter names in the table below to view more information on them.
Parameter Name | Description | Example |
---|---|---|
pdl_id | The PDL Persistent ID for a record in our Person Dataset. Note: If you enrich on ID and anything else, only ID is used and the other inputs for matching are ignored. | qEnOZ5Oh0poWnQ1luFBfVw_0000 |
name | The person's full name, at least the first and last. | Jennifer C. Jackson |
first_name | The person's first name. | Jennifer |
last_name | The person's last name. | Jackson |
middle_name | The person's middle name. | Cassandra |
location | The location in which a person lives. This can be anything from a street address to a country name. | Medford, OR USA |
street_address | The street address at which the person lives. | 1234 Main Street |
locality | The locality in which the person lives. | Boise |
region | The state or region in which the person lives. | Idaho |
country | The country in which the person lives. | United States |
postal_code | The postal code in which the person lives. If there is no value for country , the postal code is assumed to be in the US. | 83701 |
company | The name, website or social URL of the company where the person has worked. | Amazon Web Services |
school | The name, website or social URL of the university or college that the person has attended. | University of Iowa |
phone | The phone number that the person has used, in any format. | +1 555-234-1234 |
email | The email that the person has used. | [email protected] |
email_hash | The SHA-256 or MD5 email hash. | e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4 |
profile | A social profile that the person has used (see list of available social profiles). | https://linkedin.com/in/seanthorne . |
lid | The person's LinkedIn ID. | 145991517 |
birth_date | The person's birth date: either the year or a full birth date. | 1996-10-01 |
api_key | Your secret API key. Note: You can also provide this in the request header instead, as shown on the Authentication page. |
Additional Input Parameters
You are not required to use the following additional input parameters. They generally transform or control various aspects of the enrichment process (returning matches or formatting results.)
Parameter Name | Description | Example |
---|---|---|
titlecase | All text in the API responses returns as lowercase by default. Setting titlecase to true will titlecase the data in 200 responses. | false |
pretty | Whether the output should have human-readable indentation. | true |
min_likelihood | The minimum likelihood score that a response must have to return a 200 status code. | 2 |
include_if_matched | If set to true , the response will include a top-level field called matched (along with data , status and so forth), containing a value for each queried field parameter that was "matched" during our internal query. | false |
required | The fields and data points that a response must have to return a 200 status code. | "education AND (emails OR phone_numbers)" |
data_include | A comma-separated string of the fields that you want the response to include. Begin the string with a - if you want to exclude the specified fields. If you want to exclude all data from being returned, use data_include="" . | "full_name,emails.address" |
updated_title_roles | Set to true to return the updated taxonomy for job_title_role and job_title_subrole along with the new job_title_class field.Temporary parameter available from Oct 2024 - Feb 2024. | true |
Minimum Inputs
The minimum combination of data points that a request must contain in order to return a 200
response are:
profile OR email OR phone OR email_hash OR lid OR (
(
(first_name AND last_name) OR name) AND
(locality OR region OR company OR school OR location OR postal_code)
)
Output Response
When you execute an API request, we preprocess the queried data points and build them into a query, which we then execute against our API dataset. If the query yields one or more matching persons from the dataset, we return in the API response the person who is most likely the person requested, along with a 200
HTTP response code. If we do not find a match, we return a 404
HTTP response code.
Response Fields
For more details, see Output Response - Person Enrichment API
You can also click the field names in the table below to view more information on them.
Field | Description | Type |
---|---|---|
data | A matched profile record that contains fields from our Person Schema. Any fields in the profile record that do not contain any data will have a null value. | Object |
status | The response code. See a description of our error codes. | Integer |
likelihood | The degree of confidence. The field is an integer between 1 and 10 and represents how confident we are that the person we returned is the same as the person you requested. You can control the minimum likelihood score a response must have in order to return a 200 by using the min_likelihood parameter in the API request. | Integer |
Response Data Structure
Here is an example response from the Person Enrichment API:
{
"status": 200,
"likelihood": 10,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "sean thorne",
...
}
}
See Example Person Record for a full example of the fields included in the data
object.
Errors
If the request encounters an error, it will instead return an Error Response in the format described in Errors.
Updated about 1 month ago