> ## 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. # Create a recipient > Save a payout destination for one of your users. What goes inside `account` depends on the rail you pick with `account_type`. Send the same recipient twice and you get the one that already exists back, with a `202` instead of a `201`. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json post /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: post: tags: - Recipients summary: Create a recipient description: >- Save a payout destination for one of your users. What goes inside `account` depends on the rail you pick with `account_type`. Send the same recipient twice and you get the one that already exists back, with a `202` instead of a `201`. operationId: post_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: header name: Idempotency-Key required: true schema: type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: >- A value you generate for this call. Retrying with the same one returns the first recipient instead of saving a second. Reusing it with a different body is rejected with a `409`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRecipientRequest' examples: wire: summary: A company reached by wire value: user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee 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: account_type: WIRE 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' wallet: summary: A person paid in USDC value: user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee type: individual first_name: Alice last_name: Smith account: account_type: WALLET token: USDC network: polygon address: '0x0000000000000000000000000000000000000001' metadata: ledger_ref: op-4471 responses: '201': description: The recipient was saved. content: application/json: schema: $ref: '#/components/schemas/RecipientResponse' example: 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: {} '202': description: >- You already had this recipient, so nothing new was saved and the existing one comes back. The body is the same as a `201`. content: application/json: schema: $ref: '#/components/schemas/RecipientResponse' example: 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: {} '400': description: >- The request was rejected. Two shapes arrive with this status: the flat one below when a field fails its format check, and the nested one when the call itself cannot go ahead. content: application/json: examples: field: summary: A field failed its format check value: error: Invalid request data details: - path: account.bank_address.country message: String must contain exactly 2 character(s) code: too_small no-key: summary: The Idempotency-Key header is missing value: error: code: VALIDATION_ERROR message: Idempotency key is required details: {} duplicate: summary: The same details are already saved under another recipient value: error: code: VALIDATION_ERROR message: A recipient with this information already exists 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 '409': description: >- The `Idempotency-Key` was already used with a different body. Use a new key, or resend the original body. 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: IDEMPOTENCY_CONFLICT message: >- Idempotency key has already been used with different request data details: {} '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 components: schemas: CreateRecipientRequest: type: object description: >- There is no `holder_name`: the holder is taken from `first_name` and `last_name`, or from `company_name` for a company. properties: user_id: type: string format: uuid description: The user this recipient belongs to. type: type: string enum: - individual - business description: >- Whether the recipient is a person or a company. `individual` when you omit it. first_name: type: string description: Given name, for a person. middle_name: type: string description: Middle name, for a person. last_name: type: string description: Family name, for a person. company_name: type: string description: Registered name, for a company. phone: type: string description: Phone number. email: type: string description: Email address. address: type: object description: >- The recipient's own address, which is not the bank's. Required on the `ACH` and `WIRE` rails, and it has to be this object — a plain string is rejected with a `400`. 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 account: description: >- Where the money should go. `account_type` decides which other fields belong here. oneOf: - type: object description: A crypto wallet. properties: account_type: type: string enum: - WALLET description: Pick the wallet rail. token: type: string enum: - USDC - USDT description: Token the recipient receives. network: type: string enum: - polygon - solana - tron description: >- Chain to send on. Not every token works on every chain, and a pair that does not is rejected with a `400`. address: type: string description: Wallet address, which has to match the chain you picked. doc_type: type: string enum: - passport - national_id - driver_license description: Which identity document you are recording. doc_number: type: string description: Number on that document. required: - account_type - token - network - address - type: object description: A US bank account reached over ACH. properties: account_type: type: string enum: - ACH description: Pick the ACH rail. 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 enum: - checking - savings description: What kind of account it is. bank_name: type: string description: Name of the bank. bank_address: type: string description: >- Postal address of the bank, as one line of text. On this rail it is text, not an object. doc_type: type: string enum: - id - dni - passport - ein description: >- Which identity document you are recording. Use `ein` for a company. doc_number: type: string description: Number on that document. required: - account_type - routing_number - account_number - bank_name - bank_address - type: object description: A bank account reached by wire. properties: account_type: type: string enum: - WIRE description: Pick the wire rail. 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, 8 or 11 characters. account_number: type: string description: Account number, or IBAN. type: type: string enum: - checking - savings description: What kind of account it is. 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 enum: - id - dni - passport - ein description: >- Which identity document you are recording. Use `ein` for a company. doc_number: type: string description: Number on that document. required: - account_type - routing_number - account_number - bank_name - bank_address metadata: type: object additionalProperties: type: string description: >- Your own key/value pairs, returned unchanged. Up to 50 keys. A key is 1 to 40 characters and cannot contain `[` or `]`; a value is up to 500 characters. required: - user_id - account 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. ````