Batch requests

Batch endpoints let you act on up to 100 records in a single request. Each record is handled on its own: one record failing, for instance because it does not exist, does not prevent the others from going through.

Sending a batch

A batch endpoint is a POST to a /batch/{operation} path, such as /v1/people/batch/delete. The body holds a records array.

curl -X POST "https://api.folk.app/v1/people/batch/delete" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "id": "per_183ed5cc-3182-45de-84d1-d520f2604810" },
      { "id": "per_7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" }
    ]
  }'

A request with no records is accepted and does nothing.

Reading the response

Once the request itself is valid, the response is 200, whatever happened to each record. The body holds one entry in results per record you sent, in the order you sent them: the first result is the outcome of the first record, and so on. Each result carries a status:

succeeded: the operation was applied. data holds the same result as the single-record endpoint, such as the ID of the deleted record.
failed: the operation was not applied to this record. error explains why, with the same code, message and documentationUrl as the errors of single-record endpoints.

{
  "data": {
    "results": [
      {
        "status": "succeeded",
        "data": { "id": "per_183ed5cc-3182-45de-84d1-d520f2604810" }
      },
      {
        "status": "failed",
        "error": {
          "code": "NOT_FOUND",
          "message": "Person not found.",
          "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found"
        }
      }
    ]
  }
}

Records are processed together rather than one after the other in the order you sent them: a record cannot rely on the outcome of another record in the same request.

Check the status of every result rather than the status code: a 200 does not mean every record succeeded.

Requests rejected as a whole

The whole request is rejected, and no record is processed, when:

the request is not authenticated (401), or exceeds the rate limit (429);
the body is malformed, a record is invalid (such as a malformed ID), or the body has more than 100 records (422). error.details.issues gives the position of each invalid record, such as ["records", 3, "id"].

These keep the status codes described in errors, and error.details.issues says what is wrong. For instance, a request with more than 100 records returns:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid input",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
    "details": {
      "issues": [
        {
          "code": "too_big",
          "maximum": 100,
          "type": "array",
          "inclusive": true,
          "exact": false,
          "message": "A batch accepts at most 100 records.",
          "path": ["records"]
        }
      ]
    },
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

Split larger sets into several requests of at most 100 records.

Retrying a batch

Batch endpoints accept an Idempotency-Key. A retry with the same key and body returns the original response, including the result of every record, without running any of them again. To retry only the records that failed, send them in a new request with a new key.

Introducton

Available endpoints

Sending a batch

Reading the response

Requests rejected as a whole

Retrying a batch

​Sending a batch

​Reading the response

​Requests rejected as a whole

​Retrying a batch

Sending a batch

Reading the response

Requests rejected as a whole

Retrying a batch