Skip to main content
GET
List recipients
Stable since 2025-01-01 — unchanged in 2026-06-01.

Authorizations

Authorization
string
header
required

Access token from POST /auth (the data.access_token value).

x-api-key
string
header
required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version
string

Optional. The date-versioned API version to apply for this request (e.g. 2026-04-14). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default.

Example:

"2026-06-01"

Query Parameters

user_id
string<uuid>
required

REQUIRED. UUID of the user whose recipients to list. Omitting it returns 400 "user_id query parameter is required"; a user_id that does not belong to the caller returns 404 USER_NOT_FOUND.

metadata
object

Optional metadata filter using Stripe-style deepObject syntax, e.g. ?metadata[order_id]=ord_12345. Returns only recipients whose metadata matches every supplied key/value.

Response

Success.

List envelope (not a top-level array).

recipients
object[]
required
total
integer
required

Number of recipients returned.