Skip to main content


The Person Enrich API is perfect for finding specific segments of people that you need to power your projects and products. It gives you direct access to our full Person Dataset and provides many degrees of freedom, which allow you to find any kind of person(s) with a single query.


The endpoint for the Person Enrich API is

Person Search API Access and Billing

We charge per record retrieved. Each person record in the data array of the response counts as a single credit against your total package.


See Authentication and Requests to learn how to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.

Rate Limiting

The current default rate limit is 10 requests per minute.

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 the request string.

You can use the following parameters to specify information on a requested person. 

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.

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.
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).
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.)

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="".
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.

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.


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

Cookie Notice

We and third parties such as our customers, partners, and service providers use cookies and similar technologies (\"cookies\") to provide and secure our Services, to understand and improve their performance, and to serve relevant information. For more information, see our Cookie Policy.

Back to top