Skip to content

Connecting to People Data Labs#

First Steps with People Data Labs#

Set up an account with People Data Labs.

Cost

There are both free and paid options for this API.

Rate Limits

Your account plan tier will limit the number of requests each API key can make per minute. People Data Lab's documentation contains information on these limits.

How to Connect DataDistillr to People Data Labs#

To set up a data source connection for People Data Labs, you will need to have:

  • A unique name for your data source connection to be used in queries
  • An API token generated through your People Data Labs account

Data Source Form#

To locate the People Data Labs form, follow the steps in Connecting Your Data to DataDistillr. When you get to the window to choose the data source type, select API as shown below.

Data Source Wizard

On the API screen, select People Data Labs from the list of API forms.

List of APIs

The following form will appear. Instructions are below on how to find the information required to fill each field on the People Data Labs API form.

Once you have filled out all the fields, press the green 'Save' button, and your API will be connected!

People Data Labs Form

Name#

Enter any name that will help you recognize this data source within your query window.

Acceptable Characters Include

  • lowercase alphanumeric characters
  • underscores

API Key#

The API key is generated within your account page. The following steps will navigate you to its location. Once created, copy the key and enter it in the People Data Labs form under 'API Key'.

Click the API Keys button

Home page

This page contains the settings for your API token. You can modify the token's nickname and generate a new key with Roll This Key.

API keys

Endpoints#

The table below shows a list of endpoints available to connect within the DataDistillr application. If you need to connect to any endpoints not listed in the table below, please use the Custom API Form.

Endpoint Required Optional Description
/person/enrich name
first_name
last_name
middle_name
location
street_address
locality
region
country
postal_code
company
school
phone
email
email_hash
profile
lid
birth_date
min_likelihood
required
data_included
include_if_matched
titlecase
pretty
api_key
Find the single best profile matching some attributes about a particular person.
/person/retrieve/{person_id} person_id titlecase
pretty
api_key
Directly lookup a specific profile using its PDL ID.
/person/identify name
first_name
last_name
middle_name
location
street_address
locality
region
country
postal_code
company
school
phone
email
email_hash
profile
lid
birth_date
min_likelihood
required
data_included
include_if_matched
titlecase
pretty
api_key
Find the best selection of profiles associated with a particular set of attributes for a person or related persons.
/person/search query
sql
size
scroll_token
dataset
data_include
titlecase
pretty
api_key
Find all the profiles for any number of persons that satisfy some search criteria.

The endpoints above will display as follows in the nav tree once your API has successfully connected.

People Data Labs Endpoints

Sample Queries#

The following queries are intended to help you get started, and make life simpler querying within your API.

For the following examples, suppose that my People Data Labs API data source was called mypdlapi and I want to query an endpoint. In the FROM clause, the endpoint goes after the People Data Labs data source name.

FROM Clause

FROM `mypdlapi`.`<ENDPOINT>`

Enrich#

You can use the v5/person/enrich endpoint to enrich data on a person. The person enrichment API provides a one-to-one match, providing up-to-date information on a unique individual.

SELECT *
FROM `mypdlapi`.`/person/enrich`
WHERE `first_name`='John'
AND `last_name`='Doe'
AND `postal_code`='11111'
AND `phone`='555-123-4567'
LIMIT 100

Retrieve#

The Person Retrieve API allows you to use a PDL Person ID (like qEnOZ5Oh0poWnQ1luFBfVw_0000) to get back the data associated with that ID. A PDL ID is a unique and permanent identifier for each record in our dataset, and so this endpoint allows you to directly retrieve the data for the exact record you are interested in.

SELECT *
FROM `mypdlapi`.`/person/retrieve/:person_id`
WHERE `person_id`='qEnOZ5Oh0poWnQ1luFBfVw_0000'
LIMIT 100

Identify#

The Identify API allows you to use broad search inputs to recover multiple records from our person dataset. In particular, this endpoint enables functionality such as searching by just single identifying attribute (such as name, email, phone number, company, school, or location) in addition to using any combination of these attributes.

SELECT *
FROM `mypdlapi`.`/person/identify`
WHERE `first_name`='John'
AND `last_name`='Doe'
AND `postal_code`='11111'
AND `phone`='555-123-4567'
LIMIT 100

You can use the v5/person/search endpoint to write queries (in Elasticsearch or SQL format) against the dataset and return any profiles that match those queries. People Data Lab's Search API is perfect for finding specific segments of people that you need in order to power your projects and products.

SELECT *
FROM `mypdlapi`.`/person/search`
WHERE `first_name`='John'
AND `last_name`='Doe'
AND `postal_code`='11111'
AND `phone`='555-123-4567'
LIMIT 100