The PeopleDataLabs Developer Hub

Welcome to the PeopleDataLabs developer hub. You'll find comprehensive guides and documentation to help you start working with PeopleDataLabs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog

Bulk Person Enrichment API

The endpoint for the bulk enrichment api is /v5/person/bulk

Bulk Endpoint

Up to 100 persons can be enriched in a single HTTP request using the /v5/person/bulk endpoint. Enrichments executed against the bulk endpoint must be a POST. The request body of a bulk enrichment request must contain an array, requests, with 1-100 individual request objects, each containing an object params of request parameters. A JSON schema describing the structure of a /v5/person/bulk enrichment response can be found here.

import requests
import json

headers = {
   'X-Api-Key': API_KEY,
   'Content-Type': 'application/json',
}
 
data = {
   "requests": [
       {
           "params": {
               "profile": ["linkedin.com/in/seanthorne"]
           }
       },
       {
           "params": {
               "profile": ["linkedin.com/in/randrewn"]
           }
       }
   ]
}
json_response = requests.post(
   'https://api.peopledatalabs.com/v5/person/bulk',
   headers=headers,
   json=data
).json()
 
print(json.dumps(json_response))
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'

Responses are returned as an array of response objects.

[
    {"status": 200, "likelihood": 10, "data": ...},
    {"status": 200, "likelihood": 10, "data": ...}
]

Tracking Responses

Response objects are always returned in the same order as they were defined in the requests array. However you can also add an object metadata to each request, containing any information specific to that request. If metadata is defined in a request object, it will be returned, unchanged in that request's corresponding response object:

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
).json()

print(json.dumps(json_response))
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'
[
    {"metadata": {"user_id": "123"}, "status": 200, "likelihood": 10, "data": ...},
    {"metadata": {"user_id": "345"}, "status": 200, "likelihood": 10, "data": ...}
]

Any of the response filtering or formatting params documented in the Parameters section can be defined globally for all request objects:

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
).json()

print(json.dumps(json_response))
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'

Response filtering/formatting params defined locally in an individual request object will override those defined in the request body root.

Any response object in a /v5/person/bulk response will either have a status code of 200, 404, or 400. Any valid /v5/person/bulk will return with a status code of 200.

The number of remaining enrichment matches in your account will be deducted by the number of 200 responses in a bulk enrichment request as though each request was made individually.

Any malformed, unauthenticated, or throttled request will return errors in the same format as documented in the errors section.

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {"required": "names"}

response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
)
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "required": "names"
}'
{
    "status": 400,
    "error": {
        "type": "invalid_request_error",
        "message": "Request object must contain `requests` field"
    }
} 

Updated 28 days ago


Bulk Person Enrichment API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.