Release NotesDocumentationAPI ReferenceSupportAPI StatusRoadmap
Start BuildingFeedback Survey

Quickstart - Person Retrieve API

A fast hands-on introduction to the Person Retrieve API

Suggest Edits

Getting Started

In order to use our Person Retrieve API, you must have an active API key. You can look up your API key by logging into our self-serve dashboard and going to the API Keys section.

👍

Need an API Key?

If you don't have an API key, you can easily create one by signing up for a self-serve account. Check out our Self-Serve Quickstart Guide, which walks you through the sign-up process as well as shows you how to use the self-serve API dashboard.

Simple Example

As mentioned in the Overview, the Person Retrieve API is a way to directly look up records from our Person Dataset. In order to use the Person Retrieve API, you will need to know the PDL Person ID of the person that you want to look up.

Here's a quick example that demonstrates retrieving a record with a person_id of qEnOZ5Oh0poWnQ1luFBfVw_0000:

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
CLIENT = PDLPY(
    api_key="YOUR API KEY",
)

# Create a parameters JSON object
PARAMS = {
    "person_id": "qEnOZ5Oh0poWnQ1luFBfVw_0000", # The ID for the record we want
    "pretty": True
}

# Pass the parameters object to the Person Retrieve API
json_response = CLIENT.person.retrieve(**PARAMS).json()

# Print the API response in JSON format
print(json_response)

API_KEY="REPLACE WITH YOUR API KEY HERE"
PDL_PERSON_ID="qEnOZ5Oh0poWnQ1luFBfVw_0000"
curl -X GET -G \
  "https://api.peopledatalabs.com/v5/person/retrieve/${PDL_PERSON_ID}"\
  -H "X-Api-Key: ${API_KEY}" \
  --data-urlencode 'pretty=True'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

// Create a client, specifying your API key
const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

// Pass a person ID to the Person Retrieve API
PDLJSClient.person.retrieve({'id':'qEnOZ5Oh0poWnQ1luFBfVw_0000'}).then((data) => {
  // Print the API response in JSON format
  console.log(data);
}).catch((error) => {
  console.log(error);
});

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

# Set your API key
Peopledatalabs.api_key = 'YOUR API KEY'

# Pass a person ID to the Person Retrieve API
response = Peopledatalabs::Retrieve.person(person_id: "qEnOZ5Oh0poWnQ1luFBfVw_0000")

# Print the API response in JSON format
puts response

package main

import (
    "fmt"
    "encoding/json"
    "context"
)

// See https://github.com/peopledatalabs/peopledatalabs-go
import (
    pdl "github.com/peopledatalabs/peopledatalabs-go"
    pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
)

func main() {
    // Set your API key
    apiKey := "YOUR API KEY"
    // Set API key as environmental variable
    // apiKey := os.Getenv("API_KEY")

    // Create a client, specifying your API key
    client := pdl.New(apiKey)
    
    // Create a parameters JSON object
    params := pdlmodel.RetrievePersonParams {
        BaseParams: pdlmodel.BaseParams {
            Pretty: true,
        },
        PersonID: "qEnOZ5Oh0poWnQ1luFBfVw_0000",
    }
    
    // Pass the parameters object to the Person Retrieve API
    response, err := client.Person.Retrieve(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Convert the API response to JSON
        jsonResponse, jsonErr := json.Marshal(response)
        // Print the API response
        if (jsonErr == nil) {
            fmt.Println(string(jsonResponse))
        }
    }
}

import requests, json

# Set your API key
API_KEY = "YOUR API KEY"

# Set the Person Retrieve API URL
PDL_BASE_URL = "https://api.peopledatalabs.com/v5/person/retrieve"

# Set the person ID
PERSON_ID = "qEnOZ5Oh0poWnQ1luFBfVw_0000" # The ID for the record we want

# Create a parameters JSON object
PARAMS = {
    "api_key": API_KEY,
    "pretty": True
}

# Append the person ID to the API URL
URL_PATH = f"{PDL_BASE_URL}/{PERSON_ID}"

# Pass the URL path and the parameters object to the Person Retrieve API
json_response = requests.get(URL_PATH, params=PARAMS).json()

# Print the API response in JSON format
print(json_response)

📘

Note: Common Mistakes

When using the Person Retrieve API, there are a couple common mistakes, such as:

  • Using an ID that does not refer to a person profile (such as a company or school ID)
  • Passing the ID as a URL parameter rather than part of the URL path. For example, using:
    • Incorrect: v5/person/retrieve?person_id=<PDL_PERSON_ID>
    • Correct: v5/person/retrieve/<PDL_PERSON_ID>

The API returns the full person profile if the person_id exists in our dataset:

{
  "status": 200,
  "data": {
    "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
    "full_name": "sean thorne",
    ...
  },
  "billed": true
}

To see Sean's full profile that would be returned in the data object, check out our Example Person Record.

If you don't get this response, check out our Errors page for more information.

Updated about 1 month ago