Reference

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.

Endpoint

The endpoint for the Person Enrich API is

https://leadhootz2.p.rapidapi.com/api/personenrich

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.

Requests

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.

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"

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.

For more details, see Input Parameters - Person Search API