Reference - Person Identify API
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 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* | The phone number that the person has used, in any format. | +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 |
updated_title_roles | No | 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. | 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.
Updated 6 days ago