Introduction

Introduction

The APIs are organized around REST commands and use HTTP response codes to indicate successful API calls and those that produce errors. All API responses, including errors, are returned in JSON objects.

Endpoints

The APIs reside at api.peopledatalabs.com. All API requests must be made 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 use the v5/person/enrich endpoint to enrich data on a person:

import json

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

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

params = {
    "profile": ["linkedin.com/in/seanthorne"]
}

json_response = client.person.enrichment(**params).json()

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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  profile: "http://linkedin.com/in/seanthorne"
}

PDLJSClient.person.enrichment(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

params = {
    profile: ['linkedin.com/in/seanthorne']
}

json_response = Peopledatalabs::Enrichment.person(params: params)

puts json_response
import requests

API_KEY = # YOUR API KEY

pdl_url = "https://api.peopledatalabs.com/v5/person/enrich"

params = {
    "api_key": API_KEY,
    "profile": ["linkedin.com/in/seanthorne"]
}

json_response = requests.get(pdl_url,  params=params).json()

###

We also provide a 'v5/person/bulk' endpoint, 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 an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

data = {"requests": [{"params": {"profile": ["linkedin.com/in/seanthorne"]}}]}

json_response = client.person.bulk(**data).json()

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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const records = {
  requests: [
    {
      params: {
        profile: ['linkedin.com/in/seanthorne']
      }
    }
  ]
};

PDLJSClient.person.bulk(records).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

data = {requests: [{params: {profile: ['linkedin.com/in/seanthorne']}}]}

json_response = Peopledatalabs::Bulk.people(params: data)

puts json_response
import requests

API_KEY = # YOUR API KEY

pdl_url = "https://api.peopledatalabs.com/v5/person/bulk"

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

data = '{"requests": [{"params": {"profile": ["linkedin.com/in/seanthorne"]}}]}'

response = requests.post(pdl_url, headers=headers, data=data)

We provide a v5/person/search endpoint, which allows you to write queries (in Elasticsearch or SQL format) against our dataset and return any profiles that match those queries:

import json

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

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

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

P = {
  'query': ES_QUERY,
  'size': 10,
  'pretty': True
}

response = client.person.search(**P).json()

if response["status"] == 200:
  data = response['data']
  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")
import json

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

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

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

P = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

response = client.person.search(**P).json()

if response["status"] == 200:
  data = response['data']
  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")
# 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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

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

const params = {
  searchQuery: esQuery, 
  size: 10,
  pretty: true
}

PDLJSClient.person.search.elastic(params).then((data) => {
  console.log(`Number of records found: ${data['total']}`);
}).catch((error) => {
  console.log(error);
});
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

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

const params = {
  searchQuery: sqlQuery, 
  size: 10,
  pretty: true
}

PDLJSClient.person.search.sql(params).then((data) => {
  console.log(`Number of records found: ${data['total']}`);
}).catch((error) => {
  console.log(error);
});
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

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

response = Peopledatalabs::Search.people(searchType: 'elastic', query: ES_QUERY, size: 10, pretty: true)

if response['status'] == 200
    data = response['data']
    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"
end
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

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

response = Peopledatalabs::Search.people(searchType: 'sql', query: SQL_QUERY, size: 10, pretty: true)

if response['status'] == 200
    data = response['data']
    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"
end
import requests, json

API_KEY = # YOUR API KEY

PDL_URL = "https://api.peopledatalabs.com/v5/person/search"

H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

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

P = {
  'query': json.dumps(ES_QUERY),
  'size': 10,
  'pretty': True
}

response = requests.get(
  PDL_URL,
  headers=H,
  params=P
).json()

if response["status"] == 200:
  data = response['data']
  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")
import requests, json

API_KEY = # YOUR API KEY

PDL_URL = "https://api.peopledatalabs.com/v5/person/search"

H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

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

P = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

response = requests.get(
  PDL_URL,
  headers=H,
  params=P
).json()

if response["status"] == 200:
  data = response['data']
  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")

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 an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

querystring = {"website":"google.com"}

response = client.company.enrichment(**querystring)

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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const queryString = {"website":"google.com"}

PDLJSClient.company.enrichment(queryString).then((data) => {
    console.log(data);
}).catch((error) => {
    console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

querystring = {"website":"google.com"}

response = Peopledatalabs::Enrichment.company(params: querystring)

puts response
import requests

API_KEY = # ENTER YOUR API KEY

url = "https://api.peopledatalabs.com/v5/company/enrich"

querystring = {"website":"google.com"}

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

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 an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

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

P = {
  'query': ES_QUERY,
  'size': 10,
  'pretty': True
}

response = client.company.search(**P).json()

if response["status"] == 200:
  data = response['data']
  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 an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

P = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

response = client.company.search(**P).json()

if response["status"] == 200:
  data = response['data']
  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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const esQuery = {
  query: {
    bool: {
      must:[
        {"term": {"website": "google.com"}} 
      ]
    }
  }
}

const params = {
  searchQuery: esQuery, 
  size: 10,
  pretty: true
}

PDLJSClient.company.search.elastic(params).then((data) => {
    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';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const sqlQuery = `SELECT * FROM company
                    WHERE website='google.com';`;

var params = {
    searchQuery: sqlQuery, 
    size: 10,
    pretty: true
}

}

PDLJSClient.company.search.sql(params).then((data) => {
    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'

Peopledatalabs.api_key = 'YOUR API KEY'

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

response = Peopledatalabs::Search.company(searchType: 'elastic', query: ES_QUERY, size: 10, pretty: true)

if response['status'] == 200
    data = response['data']
    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"
end
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

response = Peopledatalabs::Search.company(searchType: 'sql', query: SQL_QUERY, size: 10, pretty: true)

if response['status'] == 200
    data = response['data']
    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"
end
import requests, json
API_KEY = # YOUR API KEY

PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

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

P = {
  'query': json.dumps(ES_QUERY),
  'size': 10,
  'pretty': True
}

response = requests.get(
  PDL_URL,
  headers=H,
  params=P
).json()

if response["status"] == 200:
  data = response['data']
  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

API_KEY = # YOUR API KEY

PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

P = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

response = requests.get(
  PDL_URL,
  headers=H,
  params=P
).json()

if response["status"] == 200:
  data = response['data']
  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)

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.

Use the Company Cleaner API to standardize company names:

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

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

querystring = {"website":"peopledatalabs.com"}

response = client.company.cleaner(**querystring)

print(response.text)
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  website: "peopledatalabs.com"
}

PDLJSClient.company.cleaner(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

response = Peopledatalabs::Cleaner.company(kind: 'website', value: "peopledatalabs.com")

puts response
import requests

API_KEY = # ENTER YOUR API KEY

url = "https://api.peopledatalabs.com/v5/company/clean"

querystring = {"website":"peopledatalabs.com"}

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Use the School Cleaner API to standardize school names:

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

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

querystring = {"profile":"linkedin.com/school/ucla"}

response = client.school.cleaner(**querystring)

print(response.text)
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  profile:"linkedin.com/school/ucla"
}

PDLJSClient.school.cleaner(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

response = Peopledatalabs::Cleaner.school(kind: 'profile', value: "linkedin.com/school/ucla")

puts response
import requests

API_KEY = # ENTER YOUR API KEY

url = "https://api.peopledatalabs.com/v5/school/clean"

querystring = {"profile":"linkedin.com/school/ucla"}

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Use the Location Cleaner API to standardize location names:

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

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

querystring = {"location":"239 NW 13th Ave, Portland, Oregon 97209, US"}

response = client.location.cleaner(**querystring)

print(response.text)
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const params = {
  location:"239 NW 13th Ave, Portland, Oregon 97209, US"
}

PDLJSClient.location.cleaner(params).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

Peopledatalabs.api_key = 'YOUR API KEY'

response = Peopledatalabs::Cleaner.location(value: "239 NW 13th Ave, Portland, Oregon 97209, US")

puts response
import requests

API_KEY = # ENTER YOUR API KEY

url = "https://api.peopledatalabs.com/v5/location/clean"

querystring = {"location":"239 NW 13th Ave, Portland, Oregon 97209, US"}

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

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Did this page help you?