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_addressis REQUIRED for ACH and WIRE. For WIRE it must be a structured object (street_name, city, state, postal_code, country; each line min 1;countryexactly 2 ISO letters). For ACH it is instead a free-text string. Omitting it returns400.- Top-level
addressis REQUIRED for ACH and WIRE, as a structured object (alpha-2country); a plain string is rejected with400 "address must be a structured object …". emailandphoneare OPTIONAL for every account type. (Earlier docs marked them required for WIRE / ACH — that is no longer enforced.)- There is no
holder_namefield — it is silently ignored. The holder is taken fromfirst_name/last_name(individual) orcompany_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).
Authorizations
Access token from POST /auth (the data.access_token value).
API key issued by Kira. Required on every request, including /auth.
Headers
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.
"2026-04-14"
"{{idempotency_key}}"
Body
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.
- Option 1
- Option 2
- Option 3
individual or business. Enum is exactly individual | business (an invalid value is rejected with 400 echoing this list).
individual, business 16Recipient'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.
Response
Created.
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.
individual or business. Determines whether the holder is first_name/last_name or company_name.
The payout rail: ACH, WIRE, or WALLET. Mirrors the account.account_type discriminator sent at create time.
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).
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.
Last-update timestamp. Like created_ts, this is the recipient-specific *_ts field rather than the updated_at used elsewhere.
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 (individual recipients), when provided. ASCII-normalized on write.
Family name (individual recipients). ASCII-normalized on write.
Legal company name (business recipients).
Contact phone for the recipient, when provided.
Contact email for the recipient, when provided.
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.
Your own key/value string pairs attached to the recipient.