Bulk Person Retrieve API

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.