> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # List recipients > List the recipients belonging to a single user. **A `user_id` query parameter is REQUIRED** — omitting it returns `400 "user_id query parameter is required"`. The response is an envelope (`{ recipients, total }`), not a top-level array. {/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */} Stable since **2025-01-01** — unchanged in **2026-06-01**. {/* version-stamp:end */} ## OpenAPI ````yaml /openapi/kira-api.2026-06-01.json get /v1/recipients openapi: 3.1.0 info: title: Kira API version: '2026-06-01' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Quotations - name: Payouts - name: Recipients - name: Reference - name: RFIs paths: /v1/recipients: get: tags: - Recipients summary: List recipients description: >- List the recipients belonging to a single user. **A `user_id` query parameter is REQUIRED** — omitting it returns `400 "user_id query parameter is required"`. The response is an envelope (`{ recipients, total }`), not a top-level array. operationId: get_v1-recipients parameters: - in: header name: X-Api-Version required: false description: >- 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. schema: type: string example: '2026-06-01' - in: query name: user_id required: true description: >- 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`. schema: type: string format: uuid - in: query name: metadata required: false style: deepObject explode: true description: >- 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. schema: type: object additionalProperties: type: string responses: '200': description: Success. content: application/json: schema: type: object description: List envelope (not a top-level array). properties: recipients: type: array items: $ref: '#/components/schemas/RecipientResponse' total: type: integer description: Number of recipients returned. required: - recipients - total '400': description: >- Validation error — e.g. the required `user_id` query parameter is missing (`"user_id query parameter is required"`). content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The `user_id` does not belong to the caller (`USER_NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: RecipientResponse: type: object properties: recipient_id: type: string format: uuid description: >- The recipient's UUID. **Recipients are the naming outlier:** this field is `recipient_id`, not the `id` used by the user and virtual-account resources — parse it by name. type: type: string description: >- `individual` or `business`. Determines whether the holder is `first_name`/`last_name` or `company_name`. first_name: type: string description: >- Given name (individual recipients). ASCII-normalized on write — accents are transliterated and disallowed characters stripped, so the stored value may differ from what you sent. middle_name: type: string description: >- Middle name (individual recipients), when provided. ASCII-normalized on write. last_name: type: string description: Family name (individual recipients). ASCII-normalized on write. company_name: type: string description: Legal company name (business recipients). phone: type: string description: Contact phone for the recipient, when provided. email: type: string description: Contact email for the recipient, when provided. address: description: >- The **recipient's own** address (string or structured object). This is distinct from the recipient bank's address, which lives in `account_details.bank_address`. anyOf: - type: string - type: object properties: {} account_type: type: string description: >- The payout rail: `ACH`, `WIRE`, or `WALLET`. Mirrors the `account.account_type` discriminator sent at create time. account_details: type: object description: >- Rail-specific bank or wallet details, mirroring the `account` object sent at create time. **Read-after-write caveats:** for `WIRE`, `bank_address.state` and `bank_address.postal_code` are silently returned as empty strings even when you sent them; and a `holder_name` is never stored (the holder is taken from `first_name`/`last_name` or `company_name`). properties: {} created_ts: type: string description: >- Creation timestamp. **Outlier format:** recipients use `created_ts` (not the ISO-8601 `created_at` used by user and virtual-account resources) — do not assume it round-trips as ISO 8601. updated_ts: type: string description: >- Last-update timestamp. Like `created_ts`, this is the recipient-specific `*_ts` field rather than the `updated_at` used elsewhere. metadata: type: object description: Your own key/value string pairs attached to the recipient. additionalProperties: type: string required: - recipient_id - type - account_type - account_details - created_ts - updated_ts ValidationErrorResponse: type: object description: >- Validation / request error. The body shape is **not uniform** across the API — it varies by endpoint and by which validation layer rejects the request. The fields below are the union of what may appear; treat them all as optional. Observed shapes include `{ code, message }`, `{ code, message, errors[] }`, `{ code, error, details[] }`, `{ error, details[] }`, and a nested `{ error: { code, message, details } }`. Always branch on the HTTP status, not on a fixed body shape. properties: code: type: string message: type: string error: type: - string - object description: >- A short error label (e.g. `"Invalid data"`), or on some endpoints a nested `{ code, message, details }` object. errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message details: type: - array - object description: >- Per-issue detail. Shape varies by endpoint — typically an array of `{ message }` or `{ path, message, code }`, occasionally an object. ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access token from `POST /auth` (the `data.access_token` value). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. Required on every request, including `/auth`. ````