List a batch’s recipients

GET/v1/batches/{id}/recipients

Path Parameters

idstringrequired

Query Parameters

Results are paged. When has_more is true, pass next_cursor from the response as cursor to fetch the next page.

statusqueued, paused, sent, failed, skipped, canceled
limitinteger
Default 100. Maximum 500.
cursorstring

Responses

200Page of BatchRecipient
Recipients in upload order
401Error
Missing, malformed, or revoked API key
402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429Error
Rate limit or quota exceeded

Response Fields

The body is a page: data (the array), has_more, and next_cursor (null on the last page). Each item in data:

idstring
Example: r00042.
objectbatch_recipient
tostring
statusqueued, paused, sent, failed, skipped, canceled
errorstring
Nullable. Example: carrier_error.
detailstring
Nullable.
retryableboolean
attemptsinteger
message_idstring
Nullable.
variablesobject

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

401
Missing, malformed, or revoked API key
402
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429
Rate limit or quota exceeded

const res = await fetch('https://api.jointextkit.com/v1/batches/bc_a1B2c3D4e5F6/recipients?limit=10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.TEXTKIT_API_KEY}`,
  },
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "r00042",
      "object": "batch_recipient",
      "status": "queued",
      "error": "carrier_error"
    }
  ],
  "has_more": true,
  "next_cursor": null
}