Introduction

We've organized our APIs around REST commands and use HTTP response codes to indicate successful API calls and those that produce errors. We return all API responses, including errors, as JSON objects.

Our APIs reside at api.peopledatalabs.com. When making direct API requests in URL, you must do so over HTTPS. Calls made over standard HTTP will fail. API requests without proper Authentication (a valid API key) will also fail.

https://api.peopledatalabs.com

You can also access our APIs through one of our SDKs.

Person Endpoints

Person Enrichment API

You can use the Person Enrichment API to enrich data on a person:

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 = {
    "profile": ["linkedin.com/in/seanthorne"]
}

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

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

curl -X GET \
  'https://api.peopledatalabs.com/v5/person/enrich?api_key=xxxx&profile=linkedin.com/in/seanthorne'

// 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 = {
  profile: "http://linkedin.com/in/seanthorne"
}

// Pass the parameters object to the Person Enrichment API
PDLJSClient.person.enrichment(params).then((jsonResponse) => {
  // Print the API response in JSON format
  console.log(jsonResponse);
}).catch((error) => {
  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 a parameters JSON object
PARAMS = {
    profile: ['linkedin.com/in/seanthorne']
}

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

# Print the API response in JSON format
puts JSON.dump(json_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.EnrichPersonParams {
        PersonParams: pdlmodel.PersonParams {
            Profile: []string{"linkedin.com/in/seanthorne"},
        },
    }

    // Pass the parameters object to the Person Enrichment API
    response, err := client.Person.Enrich(context.Background(), params)
    
    // Convert the API response to JSON
    jsonResponse, jsonErr := json.Marshal(response.Data)

    // Print the API response
    if err == nil && jsonErr == nil {
        fmt.Println(string(jsonResponse))
    }  
}

import requests

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

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

# Create a parameters JSON object
PARAMS = {
    "api_key": API_KEY,
    "profile": ["linkedin.com/in/seanthorne"]
}

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

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

Bulk Person Enrichment API

We also provide a Bulk Person Enrichment API, which allows you to enrich 1-100 persons in a single request (recommended for high-volume 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 array of parameters JSON objects
DATA = {"requests": [{"params": {"profile": ["linkedin.com/in/seanthorne"]}}]}

# Pass the bulk parameters object to the Bulk Person Enrichment API
json_response = CLIENT.person.bulk(**DATA).json()

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

curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" -H 'X-Api-Key: xxxx' 'Content-Type: application/json' -d'
{
    "requests": [
    	{
    		"params": {
    			"profile": ["linkedin.com/in/seanthorne"]
    		}
    	}
    ]
}

// 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 an array of parameters JSON objects
const data = {
  requests: [
    {
      params: {
        profile: ['linkedin.com/in/seanthorne']
      }
    }
  ]
};

// Pass the parameters object to the Bulk Person Enrichment API
PDLJSClient.person.bulk(data).then((jsonResponse) => {
  // Print the API response in JSON format
  console.log(jsonResponse);
}).catch((error) => {
  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 array of parameters JSON objects
DATA = {requests: [{params: {profile: ['linkedin.com/in/seanthorne']}}]}

# Pass the bulk parameters object to the Bulk Person Enrichment API
json_response = Peopledatalabs::Bulk.person(params: DATA)

# Print the API response in JSON format
puts JSON.dump(json_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 an array of parameters JSON objects
    params := pdlmodel.BulkEnrichPersonParams {
        Requests: []pdlmodel.BulkEnrichSinglePersonParams {
            {
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"linkedin.com/in/seanthorne"},
                },
            },
        },
    }

    // Pass the parameters object to the Bulk Person Enrichment API
    response, err := client.Person.BulkEnrich(context.Background(), params)
    
    // Convert the API response to JSON
    jsonResponse, jsonErr := json.Marshal(response)

    // Print the API response
    if err == nil && jsonErr == nil {
        fmt.Println(string(jsonResponse))
    }  
}

import requests

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

# Set the Bulk Person Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/person/bulk"

# Pass your API key in header
HEADERS = {
    'X-Api-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Create an array of parameters JSON objects
DATA = '{"requests": [{"params": {"profile": ["linkedin.com/in/seanthorne"]}}]}'

# Pass the bulk parameters object to the Bulk Person Enrichment API
json_response = requests.post(PDL_URL, headers=HEADERS, data=DATA).json()

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

Person Search API

You can use the Person Search API to write queries (in either Elasticsearch or SQL format) against our Person Dataset and return the profiles that match those queries:

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)

Person Retrieve API

You can use the Person Retrieve API to lookup individual person records by their person_id:

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
json_response = Peopledatalabs::Retrieve.person(person_id: "qEnOZ5Oh0poWnQ1luFBfVw_0000")

# Print the API response in JSON format
puts JSON.dump(json_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)

Bulk Person Retrieve API

We also provide a Bulk Person Retrieve API, which allows you to retrieve 1-100 persons in a single request (recommended for high-volume usage):

import requests, json

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

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

# Set headers
HEADERS = {
   'X-Api-Key': API_KEY,
   'Content-Type': 'application/json',
}

# Create a parameters JSON object with an array of person IDs
BODY = {
    "requests": [
        {"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"},
        {"id": "PzFD15NINdBWNULBBkwlig_0000"},
    ],
    "pretty": True,
    "titlecase": True,
} 

# Pass the the parameters object to the Bulk Person Retrieve API
json_response = requests.post(PDL_URL, headers=HEADERS, json=BODY).json()

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

curl -X POST "https://api.peopledatalabs.com/v5/person/retrieve/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "requests": [
        {"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000"},
        {"id": "PzFD15NINdBWNULBBkwlig_0000"}
    ]
}'

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 with an array of person IDs
    params := pdlmodel.BulkRetrievePersonParams {
        BaseParams: pdlmodel.BaseParams {
            Pretty: true,
        },
        Requests: []pdlmodel.BulkRetrieveSinglePersonParams {
            {ID: "qEnOZ5Oh0poWnQ1luFBfVw_0000"},
            {ID: "PzFD15NINdBWNULBBkwlig_0000"},
        },
        AdditionalParams: pdlmodel.AdditionalParams {
            TitleCase: true,
        },
    }
    
    // Pass the parameters object to the Bulk Person Retrieve API
    response, err := client.Person.BulkRetrieve(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))
        }
    }
}

Person Identify API

You can use the Person Identify API to access multiple strongly-associated profiles based on some broadly identifying criteria (such as a name or a street address):

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()

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

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

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(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)

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

# Print the matches in JSON format
puts JSON.dump(identities)
puts "Found #{identities.length()} identities!"

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))
    }
}

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
response = requests.request("GET", PDL_URL, params=PARAMS)

response_data = response.json()

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

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

The Differences Between Our Person-Related APIs

We offer multiple person-related APIs, so how are they different? Here's a summary of each:

Person Retrieve: Directly looks up a specific profile using its PDL ID.

Person Enrichment: Finds the single best profile matching certain attributes about a particular person.

Person Identify: Finds the best selection of profiles associated with a particular set of attributes for a person or related persons.

Person Search: Finds all the profiles for any number of persons that satisfy some search criteria.

Here's a table that summarizes some of the key differences:

	Person Retrieve	Person Enrichment	Person Identify	Person Search
Matching Type	1:1	1:1	1:Many	1:Many
Input Cleaning	No	Yes	Yes	No
Supported Query Parameters	None - direct profile lookup by ID	Only supported inputs, which must be uniquely identifying	Only supported inputs, which do not need to be uniquely identifying	Anything in the Person Schema
Number of Profiles per Unique Query	1	1	Up to 20	No limit
Sorting of Returned Profiles	N/A - only one profile is returned	N/A - only the single best-matched profile is returned	Sorted by match score	Sorted by profile completeness

The key takeaway is that the Person Identify API exists between our Person Enrichment and Search APIs in terms of functionality.

Compared to the Person Enrichment API, which returns a single record for a single person, the Person Identify API supports broader search inputs and returns multiple strongly-related profiles. This means that the Person Identify API is ideal for situations in which you do not have enough information to uniquely resolve a person and are interested in recovering highly-probable candidates. The Person Enrichment API is better suited to targeted enrichment when you have enough uniquely-identifying information.

Compared to the Person Search API, the Person Identify API has standardized input parameters and provides a match score for each returned profile. This means that you can use the Person Identify API to recover a focused selection of highly related profiles, unlike the Person Search API, which will return a potentially large demographic cross-section of our Person Dataset with more loosely-related profiles.

Company Endpoints

Company Enrichment API

Similar to how the Person Enrichment API enriches data on a person, the Company Enrichment API enriches data on a company:

# 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
QUERY_STRING = {"website":"google.com"}

# Pass the parameters object to the Company Enrichment API
response = CLIENT.company.enrichment(**QUERY_STRING)

# Print the API response
print(response.text)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/company/enrich'\
  -H 'X-Api-Key: xxxx'\
  --data-urlencode 'website=google.com'

// 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 queryString = {"website":"google.com"}

// Pass the parameters object to the Company Enrichment API
PDLJSClient.company.enrichment(queryString).then((response) => {
    // Print the API response
    console.log(response);
}).catch((error) => {
    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
QUERY_STRING = {"website":"google.com"}

# Pass the parameters object to the Company Enrichment API
response = Peopledatalabs::Enrichment.company(params: QUERY_STRING)

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CompanyParams{Website: "google.com"}
    
    params := pdlmodel.EnrichCompanyParams{
        CompanyParams: queryString,
    }
    
    // Pass the parameters object to the Company Enrichment API
    response, err := client.Company.Enrich(context.Background(), params)
    
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Company Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/enrich"

# Create a parameters JSON object
QUERY_STRING = {"website":"google.com"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
    }

# Pass the parameters object to the Company Enrichment API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Company Search API

Similar to how the Person Search API allows you to write queries that retrieve records on persons matching a criteria, the Company Search API allows you to write queries that retrieve records on companies matching a criteria:

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": {"website": "google.com"}},
      ]
    }
  }
}

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

# Pass the parameters object to the Company Search API
response = CLIENT.company.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 company
  WHERE website='google.com';
 """

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

# Pass the parameters object to the Company Search API
response = CLIENT.company.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/company/search' \
-H 'X-Api-Key: xxxx' \
--data-raw '{
  "size": 10,
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}'

# SQL
curl -X GET \
  'https://api.peopledatalabs.com/v5/company/search' \
  -H 'X-Api-Key: xxxx' \
  --data-raw '{
    "size": 10,
    "sql": "SELECT * FROM company WHERE website='\''google.com'\'';"
}'

// 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": {"website": "google.com"}} 
      ]
    }
  }
}

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

// Pass the parameters object to the Company Search API
PDLJSClient.company.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 company
                    WHERE website='google.com';`;

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

// Pass the parameters object to the Company Search API
PDLJSClient.company.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": {"website": "google.com"}},
      ]
    }
  }
}

# Pass parameters to the Company Search API
response = Peopledatalabs::Search.company(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 company
  WHERE website='google.com';
 """

# Pass parameters to the Company Search API
response = Peopledatalabs::Search.company(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{}{"website": "google.com"}},
                },
            },
        },
    }

    // 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 Company Search API
    response, err := client.Company.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 company" +
        " WHERE website='google.com';"

    // 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 Company Search API
    response, err := client.Company.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 Company Search API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

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

# Create an Elasticsearch query
ES_QUERY = {
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}

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

# Pass the parameters object to the Company 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 Company Search API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

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

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

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

# Pass the parameters object to the Company 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)

Job Title Endpoint

Job Title Enrichment API

You can use the Job Title Enrichment API to enrich data on a job title:

# 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
QUERY_STRING = {"job_title": "supply manager"}

# Pass the parameters object to the Job Title Enrichment API
response = CLIENT.job_title(**QUERY_STRING)

# Print the API response
print(response.text)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/job_title/enrich' \
  -H 'X-Api-Key: YOUR API KEY' \
  --data-urlencode 'job_title=supply manager'

// 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 queryString = {jobTitle: "supply manager"}

// Pass the parameters object to the Job Title API
PDLJSClient.jobTitle(queryString).then((data) => {
    // Print the API response
    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 parameters to the Job Title API
response = Peopledatalabs::JobTitle.retrieve("job_title":"supply manager")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.JobTitleBaseParams{JobTitle: "supply manager"}
    
    params := pdlmodel.JobTitleParams{
        JobTitleBaseParams: queryString,
    }
    
    // Pass the parameters object to the Job Title API
    response, err := client.JobTitle(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Job Title Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/job_title/enrich"

# Create a parameters JSON object
QUERY_STRING = {"job_title": "supply manager"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the Job Title Enrichment API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Skill Endpoint

Skill Enrichment API

You can use the Skill Enrichment API to enrich data on a skill:

# 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
QUERY_STRING = {"skill": "ai"}

# Pass the parameters object to the Skill Enrichment API
response = CLIENT.skill(**QUERY_STRING)

# Print the API response
print(response.text)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/skill/enrich' \
  -H 'X-Api-Key: YOUR API KEY' \
  --data-urlencode 'skill=ai'

// 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 queryString = {skill: "ai"}

// Pass the parameters object to the Skill API
PDLJSClient.skill(queryString).then((data) => {
    // Print the API response
    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 parameters to the Skill API
response = Peopledatalabs::Skill.retrieve("skill": "ai")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.SkillBaseParams{Skill: "ai"}
    
    params := pdlmodel.SkillParams{
        SkillBaseParams: queryString,
    }
    
    // Pass the parameters object to the Skill API
    response, err := client.Skill(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Skill Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/skill/enrich"

# Create a parameters JSON object
QUERY_STRING = {"skill": "ai"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the Skill Enrichment API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Supporting Endpoints

Cleaner APIs

We provide several Cleaner APIs, which you can use to standardize raw data fields for company, school and location names based on our own internal standardization criteria.

Company Cleaner

You can use the Company Cleaner API to standardize company names:

# 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
QUERY_STRING = {"website":"peopledatalabs.com"}

# Pass the parameters object to the Company Cleaner API
response = CLIENT.company.cleaner(**QUERY_STRING)

# Print the API response
print(response.text)

// 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 queryString = {
  website: "peopledatalabs.com"
}

// Pass the parameters object to the Company Cleaner API
PDLJSClient.company.cleaner(queryString).then((response) => {
  // Print the API response
  console.log(response);
}).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 parameters to the Company Cleaner API
response = Peopledatalabs::Cleaner.company(kind: 'website', value: "peopledatalabs.com")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CleanCompanyParams{Website: "peopledatalabs.com"}

    // Pass the parameters object to the Company Cleaner API
    response, err := client.Company.Clean(context.Background(), queryString)
  
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Company Cleaner API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/clean"

# Create a parameters JSON object
QUERY_STRING = {"website":"peopledatalabs.com"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the Company Cleaner API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

School Cleaner

You can use the School Cleaner API to standardize school names:

# 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
QUERY_STRING = {"profile":"linkedin.com/school/ucla"}

# Pass the parameters object to the School Cleaner API
response = CLIENT.school.cleaner(**QUERY_STRING)

# Print the API response
print(response.text)

// 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 queryString = {
  profile:"linkedin.com/school/ucla"
}

// Pass the parameters object to the School Cleaner API
PDLJSClient.school.cleaner(queryString).then((response) => {
  // Print the API response
  console.log(response);
}).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 parameters to the School Cleaner API
response = Peopledatalabs::Cleaner.school(kind: 'profile', value: "linkedin.com/school/ucla")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CleanSchoolParams {
        SchoolParams: pdlmodel.SchoolParams{Profile: "linkedin.com/school/ucla"},
    }
    
    // Pass the parameters object to the School Cleaner API
    response, err := client.School.Clean(context.Background(), queryString)
  
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the School Cleaner API URL
PDL_URL = "https://api.peopledatalabs.com/v5/school/clean"

# Create a parameters JSON object
QUERY_STRING = {"profile":"linkedin.com/school/ucla"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the School Cleaner API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Location Cleaner

You can use the Location Cleaner API to standardize location names:

# 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
QUERY_STRING = {"location":"239 NW 13th Ave, Portland, Oregon 97209, US"}

# Pass the parameters object to the Location Cleaner API
response = CLIENT.location.cleaner(**QUERY_STRING)

# Print the API response
print(response.text)

// 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 queryString = {
  location:"239 NW 13th Ave, Portland, Oregon 97209, US"
}

// Pass the parameters object to the Location Cleaner API
PDLJSClient.location.cleaner(queryString).then((data) => {
  // Print the API response
  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 parameters to the Location Cleaner API
response = Peopledatalabs::Cleaner.location(value: "239 NW 13th Ave, Portland, Oregon 97209, US")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.CleanLocationParams {
        LocationParams: pdlmodel.LocationParams{Location: "239 NW 13th Ave, Portland, Oregon 97209, US"},
    }
    
    // Pass the parameters object to the Location Cleaner API
    response, err := client.Location.Clean(context.Background(), queryString)
  
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Location Cleaner API URL
PDL_URL = "https://api.peopledatalabs.com/v5/location/clean"

# Create a parameters JSON object
QUERY_STRING = {"location":"239 NW 13th Ave, Portland, Oregon 97209, US"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the Location Cleaner API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Autocomplete API

The Autocomplete API allows you to get suggestions for Search API query values along with the number of available records for each suggestion:

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 = {
    "field": "school",
    "text": "stanf",
    "size": 10,
    "pretty": True
}

# Pass the parameters object to the Autocomplete API
json_response = CLIENT.autocomplete(**PARAMS).json()

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

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/autocomplete'\
  -H 'X-Api-Key: xxxx' \
  --data-urlencode 'field=school'\
  --data-urlencode 'text=stanf'\
  --data-urlencode 'size=10'

// 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 = {
    "field": "school",
    "text": "stanf",
    "size": 10,
    "pretty": true
}

// Pass the parameters object to the Autocomplete API
PDLJSClient.autocomplete(params).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 parameters to the Autocomplete API
json_response = Peopledatalabs::Autocomplete.retrieve(field: "school", text: "stanf", size: 10, pretty: true)

# Print the API response in JSON format
puts JSON.dump(json_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.AutocompleteParams {
        BaseParams: pdlmodel.BaseParams {
            Size: 10,
            Pretty: true,
        },
        AutocompleteBaseParams: pdlmodel.AutocompleteBaseParams {
            Field: "school",
            Text: "stanf",
        },
    }
    
    // Pass the parameters object to the Autocomplete API
    response, err := client.Autocomplete(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 Autocomplete API URL
PDL_URL = "https://api.peopledatalabs.com/v5/autocomplete"

# Create a parameters JSON object
PARAMS = {
    "api_key": API_KEY,
    "field": "school",
    "text": "stanf",
    "size": 10,
    "pretty": True
}

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

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