Reference - Person Enrichment API

Reference information for the 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 NameDescriptionExample
nameThe person's full name, at least the first and last.Jennifer C. Jackson
first_nameThe person's first name.Jennifer
last_nameThe person's last name.Jackson
middle_nameThe person's middle name.Cassandra
locationThe location in which a person lives. This can be anything from a street address to a country name.Medford, OR USA
street_addressThe street address at which the person lives.1234 Main Street
localityThe locality in which the person lives.Boise
regionThe state or region in which the person lives.Idaho
countryThe country in which the person lives.United States
postal_codeThe 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
companyThe name, website or social URL of the company where the person has worked.Amazon Web Services
schoolThe name, website or social URL of the university or college that the person has attended.University of Iowa
phoneThe phone number that the person has used, in any format.+1 555-234-1234
emailThe email that the person has used.[email protected]
email_hashThe SHA-256 or MD5 email hash.e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
profileA social profile that the person has used (see list of available social profiles).https://linkedin.com/in/seanthorne.
lidThe person's LinkedIn ID.145991517
birth_dateThe person's birth date: either the year or a full birth date.1996-10-01
data_includeA comma-separated string of the fields that you want the response to include. For example, "full_name,emails.address". 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="".
prettyWhether the output should have human-readable indentation.false
api_keyYour 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 NameDescriptionExample
titlecaseAll text in the API responses returns as lowercase by default. Setting titlecase to true will titlecase the data in 200 responses.false
min_likelihoodThe minimum likelihood score that a response must have to return a 200 status code.2
include_if_matchedIf set to true, includes a top-level field called matched (along with data, status and so forth), which includes a value for each queried field parameter that was "matched" during our internal query.false
requiredThe fields and data points that a response must have to return a 200 status code.

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.

FieldDescriptionType
dataA 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
statusThe response code. See a description of our error codes.Integer
likelihoodThe 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

Abridged 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",
            ...
     }
}

Full Example Response

Full Output Response (click to expand)
{
  "status": 200,
  "likelihood": 10,
  "data": {
    "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
    "full_name": "sean thorne",
    "first_name": "sean",
    "middle_initial": "f",
    "middle_name": "fong",
    "last_name": "thorne",
    "gender": "male",
    "birth_year": "1990",
    "birth_date": null,
    "linkedin_url": "linkedin.com/in/seanthorne",
    "linkedin_username": "seanthorne",
    "linkedin_id": "145991517",
    "facebook_url": "facebook.com/deseanthorne",
    "facebook_username": "deseanthorne",
    "facebook_id": "1089351304",
    "twitter_url": "twitter.com/seanthorne5",
    "twitter_username": "seanthorne5",
    "github_url": null,
    "github_username": null,
    "work_email": "[email protected]m",
    "personal_emails": ["[email protected]"],
    "mobile_phone": "+14155688413",
    "industry": "computer software",
    "job_title": "co-founder and chief executive officer",
    "job_title_role": null,
    "job_title_sub_role": null,
    "job_title_levels": [
      "owner",
      "cxo"
    ],
    "job_company_id": "peopledatalabs",
    "job_company_name": "people data labs",
    "job_company_website": "peopledatalabs.com",
    "job_company_size": "11-50",
    "job_company_founded": "2015",
    "job_company_industry": "computer software",
    "job_company_linkedin_url": "linkedin.com/company/peopledatalabs",
    "job_company_linkedin_id": "18170482",
    "job_company_facebook_url": "facebook.com/peopledatalabs",
    "job_company_twitter_url": "twitter.com/peopledatalabs",
    "job_company_location_name": "san francisco, california, united states",
    "job_company_location_locality": "san francisco",
    "job_company_location_metro": "san francisco, california",
    "job_company_location_region": "california",
    "job_company_location_geo": "37.77,-122.41",
    "job_company_location_street_address": "455 market street",
    "job_company_location_address_line_2": "suite 1670",
    "job_company_location_postal_code": "94105",
    "job_company_location_country": "united states",
    "job_company_location_continent": "north america",
    "job_last_updated": "2020-12-01",
    "job_start_date": "2015-03",
    "location_name": "san francisco, california, united states",
    "location_locality": "san francisco",
    "location_metro": "san francisco, california",
    "location_region": "california",
    "location_country": "united states",
    "location_continent": "north america",
    "location_street_address": null,
    "location_address_line_2": null,
    "location_postal_code": null,
    "location_geo": "37.77,-122.41",
    "location_last_updated": "2020-12-01",
    "phone_numbers": [
      "+14155688413"
    ],
    "emails": [
      {
        "address": "[email protected]",
        "type": null
      },
      {
        "address": "[email protected]",
        "type": "professional"
      },
      {
        "address": "[email protected]",
        "type": "professional"
      },
      {
        "address": "[email protected]",
        "type": "professional"
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      },
      {
        "address": "[email protected]",
        "type": "current_professional"
      }
    ],
    "interests": [
      "location based services",
      "mobile",
      "social media",
      "colleges",
      "university students",
      "consumer internet",
      "college campuses"
    ],
    "skills": [
      "entrepreneurship",
      "start ups",
      "management",
      "public speaking",
      "strategic partnerships",
      "strategy",
      "fundraising",
      "saas",
      "enterprise technology sales",
      "social networking"
    ],
    "location_names": [
      "san francisco, california, united states",
      "albany, california, united states",
      "portland, oregon, united states"
    ],
    "regions": [
      "california, united states",
      "oregon, united states"
    ],
    "countries": [
      "united states"
    ],
    "street_addresses": [],
    "experience": [
      {
        "company": {
          "name": "hallspot",
          "size": "1-10",
          "id": "hallspot",
          "founded": "2013",
          "industry": "computer software",
          "location": {
            "name": "portland, oregon, united states",
            "locality": "portland",
            "region": "oregon",
            "metro": "portland, oregon",
            "country": "united states",
            "continent": "north america",
            "street_address": "1231 northwest hoyt street",
            "address_line_2": "suite 202",
            "postal_code": "97209",
            "geo": "45.52,-122.67"
          },
          "linkedin_url": "linkedin.com/company/hallspot",
          "linkedin_id": "3019184",
          "facebook_url": null,
          "twitter_url": "twitter.com/hallspot",
          "website": "hallspot.com"
        },
        "location_names": [],
        "end_date": "2015-02",
        "start_date": "2012-08",
        "title": {
          "name": "co-founder",
          "role": null,
          "sub_role": null,
          "levels": [
            "owner"
          ]
        },
        "is_primary": false
      },
      {
        "company": {
          "name": "people data labs",
          "size": "11-50",
          "id": "peopledatalabs",
          "founded": "2015",
          "industry": "computer software",
          "location": {
            "name": "san francisco, california, united states",
            "locality": "san francisco",
            "region": "california",
            "metro": "san francisco, california",
            "country": "united states",
            "continent": "north america",
            "street_address": "455 market street",
            "address_line_2": "suite 1670",
            "postal_code": "94105",
            "geo": "37.77,-122.41"
          },
          "linkedin_url": "linkedin.com/company/peopledatalabs",
          "linkedin_id": "18170482",
          "facebook_url": "facebook.com/peopledatalabs",
          "twitter_url": "twitter.com/peopledatalabs",
          "website": "peopledatalabs.com"
        },
        "location_names": [],
        "end_date": null,
        "start_date": "2015-03",
        "title": {
          "name": "co-founder and chief executive officer",
          "role": null,
          "sub_role": null,
          "levels": [
            "owner",
            "cxo"
          ]
        },
        "is_primary": true
      }
    ],
    "education": [
      {
        "school": {
          "name": "university of oregon",
          "type": "post-secondary institution",
          "id": "64LkgfdwWYkCC2TjbldMDQ_0",
          "location": {
            "name": "eugene, oregon, united states",
            "locality": "eugene",
            "region": "oregon",
            "country": "united states",
            "continent": "north america"
          },
          "linkedin_url": "linkedin.com/school/university-of-oregon",
          "facebook_url": "facebook.com/universityoforegon",
          "twitter_url": "twitter.com/uoregon",
          "linkedin_id": "19207",
          "website": "uoregon.edu",
          "domain": "uoregon.edu"
        },
        "end_date": "2014",
        "start_date": "2010",
        "gpa": null,
        "degrees": [],
        "majors": [
          "entrepreneurship"
        ],
        "minors": []
      }
    ],
    "profiles": [
      {
        "network": "linkedin",
        "id": "145991517",
        "url": "linkedin.com/in/seanthorne",
        "username": "seanthorne"
      },
      {
        "network": "facebook",
        "id": "1089351304",
        "url": "facebook.com/deseanthorne",
        "username": "deseanthorne"
      },
      {
        "network": "twitter",
        "id": null,
        "url": "twitter.com/seanthorne5",
        "username": "seanthorne5"
      },
      {
        "network": "linkedin",
        "id": null,
        "url": "linkedin.com/in/sean-thorne-9b9a8540",
        "username": "sean-thorne-9b9a8540"
      },
      {
        "network": "angellist",
        "id": null,
        "url": "angel.co/deseanthorne",
        "username": "deseanthorne"
      },
      {
        "network": "gravatar",
        "id": null,
        "url": "gravatar.com/seanthorne5",
        "username": "seanthorne5"
      },
      {
        "network": "klout",
        "id": null,
        "url": "klout.com/seanthorne5",
        "username": "seanthorne5"
      },
      {
        "network": "aboutme",
        "id": null,
        "url": "about.me/sean_thorne",
        "username": "sean_thorne"
      }
    ]
  }
}