DocumentationAPI Explorer ToolAPI DashboardAPI StatusRoadmapSupport
Documentation
Start Building

Quickstart - Person Identify API

Suggest Edits

Getting Started

In order to use the Person Identify 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 how to use the self-serve API dashboard.

Simple Example

Let's say that you want to find all the profiles associated with the CEO of People Data Labs, Sean Thorne. The Person Identify API is the perfect tool for doing this, as it allows you to find multiple profiles using a set of input characteristics, similar to our Person Enrichment API.

The list of supported inputs includes names, email addresses, company information, profiles and much more. In this case, we'll assume all we have is Sean's name and his company's name:

Input Parameters

Parameter NameParameter Value
first_namesean
last_namethorne
companypeople data labs
prettyTrue

Using this information, you can now query the Person Identify API to find the profiles associated with Sean:

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 = {
 "first_name": "sean", 
 "last_name": "thorne", 
 "company": "people data labs",
 "pretty": True
}

# Pass the parameters object to the Person Identify API
response_data = CLIENT.person.identify(**PARAMS).json()

# Check for successful response
if json_response["status"] == 200:
   # Create a list of matches
   identities = response_data['matches']

   # Print the matches in JSON format
   print(identities)
   print(f"Found {len(identities)} identities!")
else:
   print("Identify unsuccessful. See error and try again.")
   print("error:", json_response)

API_KEY="ENTER YOUR API KEY HERE"
curl -X GET -G \
 "https://api.peopledatalabs.com/v5/person/identify"\
 -H "X-Api-Key: ${API_KEY}" \
 --data-urlencode 'first_name=sean'\
 --data-urlencode 'last_name=thorne'\
 --data-urlencode 'company="people data labs"'\
 --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" });

// Create a parameters JSON object
const params = {
  first_name: "sean", 
  last_name: "thorne", 
  company: "people data labs",
  pretty: true,
}

// Pass the parameters object to the Person Identify API
PDLJSClient.person.identify(params).then((data) => {
  // Create a list of matches
  var identities = data["matches"]
  
  // Print the matches in JSON format
  console.log(identities);
  console.log(`Found ${identities.length} identities!`)
}).catch((error) => {
  console.log("Identify unsuccessful. See error and try again.")
  console.log(error);
});

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

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

# Create a parameters JSON object
PARAMS = {
 "first_name": "sean", 
 "last_name": "thorne", 
 "company": "people data labs",
 "pretty": true
}

# Pass the parameters object to the Person Identify API
response = Peopledatalabs::Identify.person(params: PARAMS)

# Check for successful response
if json_response['status'] == 200

    # Create a list of matches
    identities = response['matches']

    # Print the matches in JSON format
    puts identities
    puts "Found #{identities.length()} identities!"
    end
else
    puts "Identify unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

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.IdentifyPersonParams {
        BaseParams: pdlmodel.BaseParams {
            Pretty: true,
        },
        PersonParams: pdlmodel.PersonParams {
            FirstName: []string{"sean"},
            LastName: []string{"thorne"},
            Company: []string{"people data labs"},
        },
    }
    
    // Pass the parameters object to the Person Identify API
    response, err := client.Person.Identify(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Create a list of matches
        identities := response.Matches
        // Convert the matches to JSON
        jsonResponse, jsonErr := json.Marshal(identities)
        // Print the matches
        if (jsonErr == nil) {
            fmt.Println(string(jsonResponse))
        }
        
        fmt.Printf("Found %d identities!\n", len(identities))
    } else {
        fmt.Println("Identify unsuccessful. See error and try again.")
        fmt.Println("error:", err)
    }
}

import requests

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

# Set the Person Identify API URL
PDL_URL = "https://api.peopledatalabs.com/v5/person/identify"

# Create a parameters JSON object
PARAMS = {
 "first_name": "sean", 
 "last_name": "thorne", 
 "company": "people data labs",
 "pretty": True,
 "api_key": API_KEY
}

# Pass the parameters object to the Person Identify API
json_response = requests.get(PDL_URL, params=PARAMS).json()

# Check for successful response
if json_response['status'] == 200:
   # Create a list of matches
   identities = json_response['matches']

   # Print the matches in JSON format
   print(identities)
   print(f"Found {len(identities)} identities!")

else:
   print("Identify unsuccessful. See error and try again.")
   print("error:", json_response)

The returned API response is a list of the records in our dataset that match the request query sorted by match strength in the format:

{
  "status": 200,
  "matches": [
    {
      "data": {
        ...
      },
      "match_score": 92,
      "matched_on": [
        "company",
        "name"
      ]
    },
    {
      "data": {
        ...
      },
      "match_score": 5,
      "matched_on": [
        "name"
      ]
    },
    ...
  ]
}

📘

Got a Different Result?

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

Each object in the matches array contains a unique profile from our Person Dataset as well as a match_score, which the API uses to sort the profiles in the matches array. You can use this profile data for various purposes. Typically, our users tend to fuse this with additional data to build more comprehensive identities.

Updated 3 months ago