> ## 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 you have saved for one user. `user_id` is required: this call always answers for a single user, never for your whole account. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/recipients openapi: 3.1.0 info: title: Kira API version: '2026-04-14' 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: Recipients - name: Quotations - name: Payouts - name: Reference paths: /v1/recipients: get: tags: - Recipients summary: List recipients description: >- List the recipients you have saved for one user. `user_id` is required: this call always answers for a single user, never for your whole account. operationId: get_v1-recipients parameters: - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-04-14' - in: query name: user_id required: true schema: type: string format: uuid example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee description: The user whose recipients you want. example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - in: query name: metadata required: false style: deepObject explode: true schema: type: object description: >- Return only the recipients carrying the metadata you name, in the `?metadata[key]=value` form. Pass more than one key to require all of them. Each key is 1 to 40 characters and cannot contain `[` or `]`. responses: '200': description: Success. content: application/json: schema: type: object properties: recipients: type: array items: $ref: '#/components/schemas/RecipientResponse' total: type: integer description: >- How many recipients came back. There is no paging on this call, so it is the length of `recipients`. example: recipients: - recipient_id: cccccccc-dddd-eeee-ffff-000000000000 type: business company_name: Acme Supplies LLC email: ap@example.com address: street_name: 500 Howard Street city: San Francisco state: CA postal_code: '94105' country: US account_type: WIRE account_details: routing_number: '000000001' account_number: '1000000001' type: checking bank_name: Example Bank National Association bank_address: street_name: 1 Second Street South city: St. Cloud state: MN postal_code: '56301' country: US doc_type: ein doc_number: '123456789' created_ts: '2026-09-01T12:00:00.000Z' updated_ts: '2026-09-01T12:00:00.000Z' metadata: {} - recipient_id: eeeeeeee-ffff-0000-1111-222222222222 type: individual first_name: Alice last_name: Smith account_type: WALLET account_details: token: USDC address: '0x0000000000000000000000000000000000000001' network: polygon created_ts: '2026-09-02T09:30:00.000Z' updated_ts: '2026-09-02T09:30:00.000Z' metadata: ledger_ref: op-4471 total: 2 '400': description: '`user_id` is missing, or a `metadata` key is not allowed.' content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: A short machine-readable reason. message: type: string description: What went wrong, in one sentence. details: type: object additionalProperties: true description: >- The values involved, when there are any. `{}` otherwise. examples: missing-user: summary: No user_id value: error: code: VALIDATION_ERROR message: user_id query parameter is required details: {} bad-metadata: summary: A metadata key is not allowed value: error: code: VALIDATION_ERROR message: metadata keys must not contain [ or ] details: {} '403': description: >- Your request was turned away before it reached the API. The message talks about routing, but any of these causes it: - The `x-api-key` header is missing or wrong. - Your bearer token has expired. Get a new one from [Get access token](/api-reference/authentication/get-access-token). - The path or the HTTP method does not match. In sandbox, check that the path sits under the `/sandbox` prefix. A missing `Authorization` header comes back as a `401` with the same body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem. '404': description: >- No user of yours has that `user_id`. Check the id, and that you are calling the environment the user was created in. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: A short machine-readable reason. message: type: string description: What went wrong, in one sentence. details: type: object additionalProperties: true description: >- The values involved, when there are any. `{}` otherwise. example: error: code: USER_NOT_FOUND message: >- User with ID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee not found or does not belong to this client details: user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee '500': description: >- Something failed on our side. Retry, and if it keeps happening contact your Kira contact with the time of the call. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: A short machine-readable reason. message: type: string description: What went wrong, in one sentence. details: type: object additionalProperties: true description: >- The values involved, when there are any. `{}` otherwise. example: error: code: INTERNAL_ERROR message: An unexpected error occurred details: {} security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production x-codeSamples: - lang: curl source: |- curl --request GET \ --url 'https://api.balampay.com/sandbox/v1/recipients?user_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \ --header 'Authorization: Bearer ' \ --header 'x-api-key: ' components: schemas: RecipientResponse: type: object description: >- One recipient. A name or contact field you never set is left out altogether rather than returned empty. properties: recipient_id: type: string format: uuid description: Recipient UUID. Send it on a payout or a quotation. type: type: string description: >- Whether the recipient is a person or a company. Available options: `individual`, `business`. See [Recipient values](/reference/recipients/values#recipient-type). first_name: type: string description: Given name of a person. middle_name: type: string description: Middle name of a person. last_name: type: string description: Family name of a person. company_name: type: string description: Registered name of a company. phone: type: string description: Phone number. email: type: string description: Email address. address: description: >- The recipient's own address, which is not the bank's. It comes back as an object when a city is on file, as a plain string when only free text was stored, and is absent when neither is. oneOf: - type: object properties: street_name: type: string description: Street and number. city: type: string description: City. state: type: string description: State or province. postal_code: type: string description: Postal code. country: type: string description: Country as an ISO 3166-1 alpha-2 code. - type: string account_type: type: string description: >- Which rail the money travels on. Available options: `ACH`, `WIRE`, `WALLET`. See [Recipient values](/reference/recipients/values#account_type). account_details: description: >- Where the money goes. Which fields you get depends on `account_type` — a wallet, an ACH account, or a wire account. anyOf: - type: object description: A crypto wallet. properties: token: type: string description: >- Token the recipient receives. Available options: `USDC`, `USDT`. See [Recipient values](/reference/recipients/values#recipient-token). address: type: string description: Wallet address. network: type: string description: >- Chain the wallet is on. Available options: `polygon`, `solana`, `tron`. See [Recipient values](/reference/recipients/values#recipient-network). doc_type: type: string description: >- Which identity document was recorded. Kira lowercases this on the way out, whatever case you sent. doc_number: type: string description: Number on that document. - type: object description: A US bank account reached over ACH. properties: routing_number: type: string description: The bank's 9-digit ABA routing number. account_number: type: string description: Account number at that bank. type: type: string description: 'Available options: `checking`, `savings`.' bank_name: type: string description: Name of the bank. bank_address: type: string description: Postal address of the bank, as one line of text. doc_type: type: string description: >- Which identity document was recorded. Kira lowercases this on the way out, whatever case you sent. doc_number: type: string description: Number on that document. - type: object description: A bank account reached by wire. properties: routing_number: type: string description: The bank's 9-digit ABA routing number. swift_code: type: string description: The bank's SWIFT or BIC code, when one was given. account_number: type: string description: Account number, or IBAN. type: type: string description: 'Available options: `checking`, `savings`.' bank_name: type: string description: Name of the bank. bank_address: type: object description: Postal address of the bank. properties: street_name: type: string description: Street and number. city: type: string description: City. state: type: string description: State or province. postal_code: type: string description: Postal code. country: type: string description: Country as an ISO 3166-1 alpha-2 code. required: - street_name - city - state - postal_code - country doc_type: type: string description: >- Which identity document was recorded. Kira lowercases this on the way out, whatever case you sent. doc_number: type: string description: Number on that document. created_ts: type: string description: When the recipient was created, as an ISO 8601 timestamp. updated_ts: type: string description: When it last changed, as an ISO 8601 timestamp. metadata: type: object additionalProperties: true description: Key/value pairs you attached. `{}` when you attached none. 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: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. ````