Quickstart - Person Search API

Getting Started

In order to use our Person Search 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. For more information, 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 Search API is a means of filtering and segmenting individual profiles included in our Person Dataset. In order to use the Person Search API, you will need to use either an Elasticsearch query or an SQL query.

Here's a quick example to search for profiles whose location_country is mexico, whose job_title_role is health, and whose record includes at least one phone_numbers:

❗️
Heads Up! Credit Usage
Person Search API calls cost the number of total search results returned.
If you are making a search that could have a large number of results, make sure to use the size parameter to set the maximum number of results and cap your credit usage.

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 an Elasticsearch query
ES_QUERY = {
  'query': {
    'bool': {
        'must': [
            {'term': {'location_country': "mexico"}},
            {'term': {'job_title_role': "health"}},
            {'exists': {'field': "phone_numbers"}}
      ]
    }
  }
}

# Create a parameters JSON object
PARAMS = {
  'query': ES_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Person Search API
response = CLIENT.person.search(**PARAMS).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"Successfully grabbed {len(data)} records from PDL.")
  print(f"{response['total']} total PDL records exist matching this query.")
else:
  print("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)

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 an SQL query
SQL_QUERY = \
"""
  SELECT * FROM person
  WHERE location_country='mexico'
  AND job_title_role='health'
  AND phone_numbers IS NOT NULL;
 """

# Create a parameters JSON object
PARAMS = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Person Search API
response = CLIENT.person.search(**PARAMS).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"Successfully grabbed {len(data)} records from PDL.")
  print(f"{response['total']} total PDL records exist matching this query.")
else:
  print("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)

# Elasticsearch
curl -X GET 'https://api.peopledatalabs.com/v5/person/search' \
-H 'X-Api-Key: xxxx' \
--data-raw '{
  "size": 10,
  "query": {
    "bool": {
      "must": [
        {"term": {"location_country": "mexico"}},
        {"term": {"job_title_role": "health"}},
        {"exists": {"field": "phone_numbers"}}
      ]
    }
  }
}'

# SQL
curl -X GET \
  'https://api.peopledatalabs.com/v5/person/search' \
  -H 'X-Api-Key: xxxx' \
  --data-raw '{
    "size": 10,
    "sql": "SELECT * FROM person WHERE location_country='\''mexico'\'' AND job_title_role='\''health'\'' AND phone_numbers IS NOT NULL;"
}'

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

import fs from 'fs';

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

// Create an Elasticsearch query
const esQuery = {
  query: {
    bool: {
      must:[
        {term: {location_country: "mexico"}}, 
        {term: {job_title_role: "health"}}, 
        {exists: {field: "phone_numbers"}}
      ]
    }
  }
}

// Create a parameters JSON object
const params = {
  searchQuery: esQuery, 
  size: 10,
  pretty: true
}

// Pass the parameters object to the Person Search API
PDLJSClient.person.search.elastic(params).then((data) => {
    // Write out all profiles found to file
    fs.writeFile("my_pdl_search.jsonl", Buffer.from(JSON.stringify(data.data)), (err) => {
        if (err) throw err;
    });
    console.log(`Successfully grabbed ${data.data.length} records from PDL.`);
    console.log(`${data["total"]} total PDL records exist matching this query.`)
}).catch((error) => {
    console.log("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
    console.log(error);
});

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

import fs from 'fs';

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

// Create an SQL query
const sqlQuery = `SELECT * FROM person 
                  WHERE location_country='mexico' 
                  AND job_title_role='health'
                  AND phone_numbers IS NOT NULL;`

// Create a parameters JSON object
const params = {
  searchQuery: sqlQuery, 
  size: 10,
  pretty: true
}

// Pass the parameters object to the Person Search API
PDLJSClient.person.search.sql(params).then((data) => {
    // Write out all profiles found to file
    fs.writeFile("my_pdl_search.jsonl", Buffer.from(JSON.stringify(data.data)), (err) => {
        if (err) throw err;
    });
    console.log(`Successfully grabbed ${data.data.length} records from PDL.`);
    console.log(`${data["total"]} total PDL records exist matching this query.`)
}).catch((error) => {
    console.log("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
    console.log(error);
});

require 'json'

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

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

# Create an Elasticsearch query
ES_QUERY = {
  "query": {
    "bool": {
        "must": [
            {"term": {"location_country": "mexico"}},
            {"term": {"job_title_role": "health"}},
            {"exists": {"field": "phone_numbers"}}
      ]
    }
  }
}

# Pass parameters to the Person Search API
response = Peopledatalabs::Search.person(searchType: 'elastic', query: ES_QUERY, size: 10, pretty: true)

# Check for successful response
if response['status'] == 200
    data = response['data']
    # Write out each profile found to file
    File.open("my_pdl_search.jsonl", "w") do |out|
        data.each { |record| out.write(JSON.dump(record) + "\n") }
    end
    puts "Successfully grabbed #{data.length()} records from PDL."
    puts "#{response['total']} total PDL records exist matching this query."
else
    puts "NOTE: The carrier pigeons lost motivation in flight. See error and try again."
    puts "Error: #{response}"
end

require 'json'

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

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

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM person
  WHERE location_country='mexico'
  AND job_title_role='health'
  AND phone_numbers IS NOT NULL;
 """

# Pass parameters to the Person Search API
response = Peopledatalabs::Search.person(searchType: 'sql', query: SQL_QUERY, size: 10, pretty: true)

# Check for successful response
if response['status'] == 200
    data = response['data']
    # Write out each profile found to file
    File.open("my_pdl_search.jsonl", "w") do |out|
        data.each { |record| out.write(JSON.dump(record) + "\n") }
    end
    puts "Successfully grabbed #{data.length()} records from PDL."
    puts "#{response['total']} total PDL records exist matching this query."
else
    puts "NOTE: The carrier pigeons lost motivation in flight. See error and try again."
    puts "Error: #{response}"
end

package main

import (
    "fmt"
    "os"
    "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 an Elasticsearch query
    elasticSearchQuery := map[string]interface{} {
        "query": map[string]interface{} {
            "bool": map[string]interface{} {
                "must": []map[string]interface{} {
                    {"term": map[string]interface{}{"location_country": "mexico"}},
                    {"term": map[string]interface{}{"job_title_role": "health"}},
                    {"exists": map[string]interface{}{"field": "phone_numbers"}},
                },
            },
        },
    }

    // Create a parameters JSON object
    params := pdlmodel.SearchParams {
        BaseParams: pdlmodel.BaseParams {
            Size: 10,
            Pretty: true,
        },
        SearchBaseParams: pdlmodel.SearchBaseParams {
            Query: elasticSearchQuery,
        },
    }
    
    // Pass the parameters object to the Person Search API
    response, err := client.Person.Search(context.Background(), params)
    // Check for successful response
    if err == nil {
        data := response.Data
        // Create file
        out, outErr := os.Create("my_pdl_search.jsonl")
        defer out.Close()
        if (outErr == nil) {
            for i := range data {
                // Convert each profile found to JSON
                record, jsonErr := json.Marshal(data[i])
                // Write out each profile to file
                if (jsonErr == nil) {
                    out.WriteString(string(record) + "\n")
                }
            }
            out.Sync()
        }
        fmt.Printf("Successfully grabbed %d records from PDL.\n", len(data))
        fmt.Printf("%d total PDL records exist matching this query.\n", response.Total)
    } else {
        fmt.Println("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
        fmt.Println("Error:", err)
    }  
}

package main

import (
    "fmt"
    "os"
    "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 an SQL query
    sqlQuery := "SELECT * FROM person" +
        " WHERE location_country='mexico'" +
        " AND job_title_role='health'" +
        " AND phone_numbers IS NOT NULL;"

    // Create a parameters JSON object
    params := pdlmodel.SearchParams {
        BaseParams: pdlmodel.BaseParams {
            Size: 10,
            Pretty: true,
        },
        SearchBaseParams: pdlmodel.SearchBaseParams {
            SQL: sqlQuery,
        },
    }
    
    // Pass the parameters object to the Person Search API
    response, err := client.Person.Search(context.Background(), params)
    // Check for successful response
    if err == nil {
        data := response.Data
        // Create file
        out, outErr := os.Create("my_pdl_search.jsonl")
        defer out.Close()
        if (outErr == nil) {
            for i := range data {
                // Convert each profile found to JSON
                record, jsonErr := json.Marshal(data[i])
                // Write out each profile to file
                if (jsonErr == nil) {
                    out.WriteString(string(record) + "\n")
                }
            }
            out.Sync()
        }
        fmt.Printf("Successfully grabbed %d records from PDL.\n", len(data))
        fmt.Printf("%d total PDL records exist matching this query.\n", response.Total)
    } else {
        fmt.Println("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
        fmt.Println("Error:", err)
    }  
}

import requests, json

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

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

# Set headers
HEADERS = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

# Create an Elasticsearch query
ES_QUERY = {
  'query': {
    'bool': {
        'must': [
            {'term': {'location_country': "mexico"}},
            {'term': {'job_title_role': "health"}},
            {'exists': {'field': "phone_numbers"}}
      ]
    }
  }
}

# Create a parameters JSON object
PARAMS = {
  'query': json.dumps(ES_QUERY),
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Person Search API
response = requests.get(
  PDL_URL,
  headers=HEADERS,
  params=PARAMS
).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"Successfully grabbed {len(data)} records from PDL.")
  print(f"{response['total']} total PDL records exist matching this query.")
else:
  print("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)

import requests, json

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

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

# Set headers
HEADERS = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM person
  WHERE location_country='mexico'
  AND job_title_role='health'
  AND phone_numbers IS NOT NULL;
 """

# Create a parameters JSON object
PARAMS = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Person Search API
response = requests.get(
  PDL_URL,
  headers=HEADERS,
  params=PARAMS
).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"Successfully grabbed {len(data)} records from PDL.")
  print(f"{response['total']} total PDL records exist matching this query.")
else:
  print("NOTE: The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)

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

{
  "status": 200,
  "data": [
    {
      "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
      "full_name": "sean thorne",
      ...
    },
    ...
  ],
"scroll_token": "1117$12.176522"  
"total": 94
}

The objects in the data array will follow the Person Schema. For a full example, see the Example Person Record.

Troubleshooting

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

Quickstart - Person Search API

Getting Started

👍
Need an API Key?

Simple Example

❗️
Heads Up! Credit Usage

Troubleshooting

Getting Started

👍Need an API Key?

Simple Example

❗️Heads Up! Credit Usage

Troubleshooting

👍
Need an API Key?

❗️
Heads Up! Credit Usage