> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/person-retrieve-api) in one request.

<Frame>
  <img src="https://mintcdn.com/peopledatalabs/0Dx9WJ8G6RwVLrEr/images/docs/dd7a34c-Bulk_Person_Retrieve_API_Summary.svg?fit=max&auto=format&n=0Dx9WJ8G6RwVLrEr&q=85&s=f2ef24ca863fb6c38809734b73953ae2" alt="Bulk Person Retrieve API Summary.svg" width="960" height="540" data-path="images/docs/dd7a34c-Bulk_Person_Retrieve_API_Summary.svg" />
</Frame>

## 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`          |

```json JSON theme={null}
{
  "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](/docs/bulk-person-retrieve#tracking-responses) 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](/docs/errors) for a detailed breakdown on all possible status codes.

## Example

<CodeGroup>
  ```python Python3 theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"}
      ]
  }'
  ```

  ```go Go expandable theme={null}
  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))
          }
      }
  }
  ```
</CodeGroup>

```json JSON theme={null}
[
  {
    "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:

<CodeGroup>
  ```python Python3 expandable theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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
              }
          }
      ]
  }'
  ```

  ```go Go expandable theme={null}
  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))
          }
      }
  }
  ```
</CodeGroup>

Expected Output:

```json JSON theme={null}
[
	{"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](/docs/errors) page.

<CodeGroup>
  ```python Python3 theme={null}
  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)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.peopledatalabs.com/v5/person/retrieve/bulk" \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: XXX' \
  -d ' {
  	"required": "names"
  }'
  ```

  ```go Go expandable theme={null}
  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)
      }
  }
  ```
</CodeGroup>

```json JSON theme={null}
{
    "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:

1. Add the `Accept-Encoding: gzip` header to your request headers. We will gzip-compress the responses, which will be around five times smaller.

2. Retrieve less records per call. Enriching around 50 records instead of 100 should bypass this limitation.


## Related topics

- [July 2022 Release Notes](/changelog/july-2022-release-notes-v19.md)
- [Bulk Person Enrichment API](/docs/bulk-enrichment-api.md)
- [Person Endpoints](/docs/person-endpoints.md)
- [April 2022 Release Notes](/changelog/april-2022-release-notes-v18.md)
- [January 2023 Release Notes](/changelog/january-2023-release-notes-v21.md)