Bulk Person Retrieve API
Directly look up multiple person profiles by their PDL IDs
Overview
The Bulk Retrieve API provides a way to retrieve multiple profiles using the Person Retrieve API in one request.
Request Format
The endpoint for the Bulk Person Retrieve API is POST https://api.peopledatalabs.com/v5/person/retrieve/bulk
. You must use POST
requests.
You can retrieve up to 100 persons in a single HTTP request.
The request body must contain an array called requests
with 1-100 individual request objects, each containing a valid PDL ID.
Field Name | Description | Type |
---|---|---|
requests | All requests to make in the bulk enrichment. | Array \[Object] |
id | The PDL ID of the profile to retrieve. | String |
{
"requests": [
{ "id": "PDL ID TO RETRIEVE" },
...
]
}
Response Format
The bulk response is a JSON Array of objects with the following fields:
Field Name | Type | Description |
---|---|---|
data | Object | The person response object. |
status | Integer | The HTTP status code. |
billed | Boolean | A flag that indicates whether we charged a credit for the record. |
metadata | Object | [OPTIONAL]Any metadata that you included in the request. |
Note: Metadata is on a per-request basis and generally you should use it to connect requests to responses within an API call. See this section for more information.
The order the objects appear in the response list is the same as the order of the IDs in the input requests
array.
Each response contains an individual status code that shows whether the retrieval for that particular request was successful (200
) or not. See Errors for a detailed breakdown on all possible status codes.
Example
import requests, json
# Set your API key
API_KEY = "YOUR API KEY"
# Set the Bulk Person Retrieve API URL
PDL_BASE_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 using POST method
json_response = requests.post(PDL_BASE_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))
}
}
}
[
{
"status": 200,
"data": {
"id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
"full_name": "Sean Thorne",
...
},
"billed": false
},
{
"status": 200,
"data": {
"id": "PzFD15NINdBWNULBBkwlig_0000",
"full_name": "Hayden Conrad",
...
},
"billed": false
}
]
Tracking Responses
The API always return response objects in the same order as they were defined in the requests
array. However, you can also add a metadata
object to each request, containing any information specific to that request. If you define metadata
in a request object, the API will return it unchanged in that request's corresponding response object:
import requests, json
# Set your API key
API_KEY = "YOUR API KEY"
# Set the Bulk Person Retrieve API URL
PDL_BASE_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",
# Include metadata object
"metadata": {
"user_id": 123
},
},
{
"id": "PzFD15NINdBWNULBBkwlig_0000",
# Include metadata object
"metadata": {
"user_id": 569
},
},
],
"pretty": True,
"titlecase": True,
}
# Pass the the parameters object to the Bulk Person Retrieve API
json_response = requests.post(PDL_BASE_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",
"metadata": {
"user_id": 123
}
},
{
"id": "PzFD15NINdBWNULBBkwlig_0000",
"metadata": {
"user_id": 569
}
}
]
}'
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",
// Include metadata object
Metadata: map[string]string {
"user_id": "123",
},
},
{
ID: "PzFD15NINdBWNULBBkwlig_0000",
// Include metadata object
Metadata: map[string]string {
"user_id": "569",
},
},
},
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))
}
}
}
Expected Output:
[
{"status": 200, "data": ..., "metadata": {"user_id": "123"}},
{"status": 200, "data": ..., "metadata": {"user_id": "569"}}
]
Usage Notes
Any response object in a /v5/person/retrieve/bulk
response will either have a status code of 200
, 404
or 400
. Any valid /v5/person/retrieve/bulk
will return with a status code of 200
.
We will deduct the number of 200
responses to a bulk retrieve request from the number of remaining retrieve matches in your account as though each request was made individually.
Malformed, Unauthenticated or Throttled Requests
Any malformed, unauthenticated or throttled requests will return errors in the same format as documented in the Errors page.
import requests, json
# Set your API key
API_KEY = "YOUR API KEY"
# Set the Bulk Person Retrieve API URL
PDL_BASE_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 without a requests array
BODY = {
"required": "names",
"pretty": True,
"titlecase": True,
}
# Pass the the parameters object to the Bulk Person Retrieve API
json_response = requests.post(PDL_BASE_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 ' {
"required": "names"
}'
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 without a requests array
params := pdlmodel.BulkRetrievePersonParams {
BaseParams: pdlmodel.BaseParams {
Pretty: true,
},
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))
}
} else {
fmt.Println(err)
}
}
{
"status": 400,
"error": {
"type": "invalid_request_error",
"message": "Missing key: 'requests'"
}
}
Bulk Request Limitations
Currently, due to infrastructure constraints, there is a 1MB limit on API responses. Most bulk requests will not hit this limit. However, an 80-100 record bulk request that returns rich records may approach or go over this limitation.
Here are some ways to ensure that you don't run into this limitation:
-
Add the
Accept-Encoding: gzip
header to your request headers. We will gzip-compress the responses, which will be around five times smaller. -
Retrieve less records per call. Enriching around 50 records instead of 100 should bypass this limitation.
Updated about 1 month ago