Skip to main content

​
How batching works

Several Finch endpoints — /individual, /employment, and /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. 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. Each batch endpoint enforces a maximum batch size. Build your application to split requests[] into chunks that stay within these limits before sending — a request over the limit fails before Finch processes any item in the batch. For example, to request 25,000 individuals from /individual, split the individual_ids into three requests of 10,000, 10,000, and 5,000 items rather than sending all 25,000 in one call.

​
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 (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 (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 for the enrollment request format and how to verify the job.
  • 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 limit errors

A request with more items than an endpoint’s max batch size returns a 422 with a finch_code of batch_limit_exceeded, and Finch does not process any item in the batch:
Split the request into smaller batches — retrying the same request without changing it fails again. See Mitigate Errors for the full error format.

​
Per-item errors

When a batch request is within the size limit, Finch can still return errors for individual items inside it. Finch returns these errors two ways, both in the format described in 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.

​
Checkpoint + Next Step

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 for the others.

​
Learn more