> ## 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 > Create a recipient (payout destination). The `account` object is a discriminated union on `account_type`; the required sub-fields vary by type. Notes: - **`account.bank_address` is REQUIRED for ACH and WIRE.** For WIRE it must be a structured object (`street_name, city, state, postal_code, country`; each line min 1; `country` exactly 2 ISO letters). For ACH it is instead a free-text string. Omitting it returns `400`. - **Top-level `address` is REQUIRED for ACH and WIRE, as a structured object** (alpha-2 `country`); a plain string is rejected with `400 "address must be a structured object …"`. - **`email` and `phone` are OPTIONAL for every account type.** (Earlier docs marked them required for WIRE / ACH — that is no longer enforced.) - There is **no `holder_name`** field — it is silently ignored. The holder is taken from `first_name` / `last_name` (individual) or `company_name` (business). **Status codes.** `201` on success; `202` when the recipient already existed and the existing record is returned (idempotent — same `RecipientResponse` body as `201`); `400` validation error — including a duplicate recipient (`"A recipient with this information already exists"`); `401` unauthorized; `404` when the `user_id` does not belong to the caller (`USER_NOT_FOUND`); `409` when the same `Idempotency-Key` is reused with a different body (`IDEMPOTENCY_CONFLICT`). {/* 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 post /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: post: tags: - Recipients summary: Create a recipient description: >- Create a recipient (payout destination). The `account` object is a discriminated union on `account_type`; the required sub-fields vary by type. Notes: - **`account.bank_address` is REQUIRED for ACH and WIRE.** For WIRE it must be a structured object (`street_name, city, state, postal_code, country`; each line min 1; `country` exactly 2 ISO letters). For ACH it is instead a free-text string. Omitting it returns `400`. - **Top-level `address` is REQUIRED for ACH and WIRE, as a structured object** (alpha-2 `country`); a plain string is rejected with `400 "address must be a structured object …"`. - **`email` and `phone` are OPTIONAL for every account type.** (Earlier docs marked them required for WIRE / ACH — that is no longer enforced.) - There is **no `holder_name`** field — it is silently ignored. The holder is taken from `first_name` / `last_name` (individual) or `company_name` (business). **Status codes.** `201` on success; `202` when the recipient already existed and the existing record is returned (idempotent — same `RecipientResponse` body as `201`); `400` validation error — including a duplicate recipient (`"A recipient with this information already exists"`); `401` unauthorized; `404` when the `user_id` does not belong to the caller (`USER_NOT_FOUND`); `409` when the same `Idempotency-Key` is reused with a different body (`IDEMPOTENCY_CONFLICT`). operationId: post_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: header name: Idempotency-Key required: true schema: type: string format: uuid example: '{{idempotency_key}}' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRecipientRequest' examples: create-recipient-wire: summary: Create Recipient — Wire value: user_id: '{{verified_user_id}}' first_name: Jane last_name: Doe email: jane@example.com address: street_name: 123 Market St city: San Francisco state: CA postal_code: '94105' country: US account: account_type: WIRE routing_number: '021000021' account_number: '1234567890' bank_name: Example Bank, N.A. bank_address: street_name: 1 Bank Plaza city: New York state: NY postal_code: '10001' country: US responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/RecipientResponse' '202': description: >- Accepted — the recipient already existed; the existing record is returned (idempotent). Same body as `201`. content: application/json: schema: $ref: '#/components/schemas/RecipientResponse' '400': description: Validation error. 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' '409': description: >- The same `Idempotency-Key` was reused with a different body (`IDEMPOTENCY_CONFLICT`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: CreateRecipientRequest: type: object properties: user_id: type: string format: uuid type: type: string enum: - individual - business description: >- `individual` or `business`. Enum is exactly `individual` | `business` (an invalid value is rejected with 400 echoing this list). first_name: type: string middle_name: type: string last_name: type: string company_name: type: string phone: type: string maxLength: 16 email: type: string format: email address: description: >- Recipient's address. **Required for the US bank rails** — a recipient whose `account.account_type` is `ACH` or `WIRE` must include a non-empty top-level `address`, or the create returns `400` (e.g. `"address is required for WIRE accounts"`). For `ACH` and `WIRE` it must be the **structured object** form below (all five fields required; a plain string is rejected with `400`). Optional for all other rails. This is distinct from `account.bank_address` (the recipient bank's address), which the bank rails require separately. anyOf: - type: string - type: object properties: street_name: type: string minLength: 1 city: type: string minLength: 1 state: type: string minLength: 1 postal_code: type: string minLength: 1 country: type: string minLength: 2 maxLength: 2 required: - street_name - city - state - postal_code - country account: oneOf: - type: object properties: account_type: type: string enum: - WALLET token: type: string enum: - USDC - USDT - COPm address: type: string minLength: 1 description: >- Destination wallet address. Validated against the network's format, or the request returns `400`: `polygon` — EVM address (`0x` followed by 40 hex characters); `solana` — base58, 32–44 characters; `tron` — starts with `T`, 34 characters (base58check). network: type: string enum: - polygon - solana - tron - ethereum description: >- Blockchain network. Only these `token`/`network` pairs are accepted (any other combination returns `400 "Invalid token/network combination"`): `USDC`/`polygon`, `USDC`/`solana`, `USDT`/`polygon`, `USDT`/`solana`, `USDT`/`tron`, `COPm`/`polygon`. `ethereum` is accepted by the field but has no valid token pairing, so it is always rejected. doc_type: type: string enum: - passport - national_id - driver_license doc_number: type: string minLength: 1 required: - account_type - token - address - network - type: object properties: account_type: type: string enum: - ACH routing_number: type: string pattern: ^\d{9}$ account_number: type: string type: type: string enum: - checking - savings bank_name: type: string bank_address: type: string doc_type: type: string enum: - id - dni - passport - ein doc_number: type: string minLength: 1 required: - account_type - routing_number - account_number - bank_name - bank_address - type: object properties: account_type: type: string enum: - WIRE routing_number: type: string pattern: ^\d{9}$ swift_code: type: string pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ account_number: type: string type: type: string enum: - checking - savings bank_name: type: string bank_address: type: object properties: street_name: type: string minLength: 1 city: type: string minLength: 1 state: type: string minLength: 1 postal_code: type: string minLength: 1 country: type: string minLength: 2 maxLength: 2 required: - street_name - city - state - postal_code - country doc_type: type: string enum: - id - dni - passport - ein doc_number: type: string minLength: 1 required: - account_type - routing_number - account_number - bank_name - bank_address description: >- In responses this object comes back **renamed**: a top-level `account_type` plus the details under `account_details` (see `RecipientResponse`) — there is no `account` field on the way out. metadata: type: object additionalProperties: type: string maxLength: 500 required: - user_id - account allOf: - if: properties: account: properties: account_type: enum: - ACH - WIRE required: - account_type required: - account then: required: - address 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`. ````