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

# Batch Requests

> Batch multiple IDs into a single request to Finch's individual, employment, pay-statement, and deductions endpoints to cut API calls and rate limit risk.

## How batching works

Several Finch endpoints — [`/individual`](/api-reference/organization/individual), [`/employment`](/api-reference/organization/employment), and [`/pay-statement`](/api-reference/payroll/pay-statement) — accept multiple IDs in a single request. Finch returns one response with an array of objects, one per ID sent.

For example, retrieving individual details for a 1,000-person company by calling `/individual` 1,000 times quickly exhausts your [rate limit](/api-reference/development-guides/Rate-Limits). Since there's no limit on the number of IDs per request, batch all 1,000 `individual_ids` into a single call instead — Finch returns one response with an array of 1,000 individual detail objects. Batching also cuts down the number of round trips your application makes, on top of helping you stay within your rate limit.

Determine the batch size that fits your use case, then pass all the required IDs in a single request:

```json theme={null}
{
  "requests": [
    {
      "individual_id": "772b3c4f-d764-433d-bd69-ff8bbac33ffe"
    },
    {
      "individual_id": "a7a77065-0f68-418d-a85a-da24fb2139b7"
    },
    ...
    {
      "individual_id": "84364585-c2ce-40aa-bcc0-666ac9577315"
    }
  ]
}
```

### Batching deductions requests

Three deductions endpoints also accept multiple individuals in a single call, but with different request shapes than `/individual`, `/employment`, and `/pay-statement`:

* [Get Deductions for Individuals](/api-reference/deductions/get-deductions-for-individuals) (`GET /benefits/{benefit_id}/individuals`) — pass a comma-delimited `individual_ids` query parameter instead of a request body. Finch returns an array of `{individual_id, code, body}` objects, one per ID.
* [Enroll Individuals in Deductions](/api-reference/deductions/enroll-individuals-in-deductions) (`POST /benefits/{benefit_id}/individuals`) — pass an array of enrollment objects directly as the request body, one per individual. This is an asynchronous batch write: Finch returns a single `job_id` for the whole batch instead of a per-item response. See [Write Data](/implementation-guide/API-Calls/Write-Data) for the enrollment request format and how to verify the job.
* [Unenroll Individuals from Deductions](/api-reference/deductions/unenroll-individuals-from-deductions) (`DELETE /benefits/{benefit_id}/individuals`) — pass an `individual_ids` array in the request body. Like enrollment, this is an asynchronous batch write that returns a single `job_id` for the whole batch.

## Batch Errors

When calling a batch endpoint, handle errors returned in the batch format. Finch returns batch errors two ways, both in the format described in [Error Types](/api-reference/development-guides/errors/Error-Types):

1. An error per batch request item within the response body.
2. An error at the HTTP status code level.

A `200` HTTP status code doesn't mean every item in the batch succeeded — check each item's own `code` in the response body.

```json theme={null}
// HTTP 200 status code
{
  "responses": [
    {
      "individual_id": "4f66ec6e-f73c-41e6-bc14-bb2ae53288a0",
      "code": 404,
      "body": {
        "code": 404,
        "name": "not_found_error",
        "finch_code": "individual_not_found",
        "message": "No individual with id 4f66ec6e-f73c-41e6-bc14-bb2ae53288a0 found"
      }
    }
  ]
}
```

***

## Checkpoint + Next Step

<Check>
  After completing this step, your application can send thousands of IDs in a single HTTP request and handle each item's result in the response body. Batch errors are one type of error your application can encounter — see [Mitigate Errors](/implementation-guide/Backend-Application/Mitigate-Errors) for the others.
</Check>

## Learn more

* [Read Data](/implementation-guide/API-Calls/Read-Data)
* [Error Types](/api-reference/development-guides/errors/Error-Types)
* [Error Handling](/api-reference/development-guides/errors/Error-Handling)
* [Rate Limits](/api-reference/development-guides/Rate-Limits)