Skip to main content
POST
Create a recipient
Stable since 2025-01-01 — unchanged in 2026-06-01.

Authorizations

Authorization
string
header
required

Access token from POST /auth (the data.access_token value).

x-api-key
string
header
required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version
string

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.

Example:

"2026-06-01"

Idempotency-Key
string<uuid>
required
Example:

"{{idempotency_key}}"

Body

application/json
user_id
string<uuid>
required
account
object
required

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.

type
enum<string>

individual or business. Enum is exactly individual | business (an invalid value is rejected with 400 echoing this list).

Available options:
individual,
business
first_name
string
middle_name
string
last_name
string
company_name
string
phone
string
Maximum string length: 16
email
string<email>
address

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.

metadata
object

Response

Created.

recipient_id
string<uuid>
required

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
string
required

individual or business. Determines whether the holder is first_name/last_name or company_name.

account_type
string
required

The payout rail: ACH, WIRE, or WALLET. Mirrors the account.account_type discriminator sent at create time.

account_details
object
required

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).

created_ts
string
required

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
string
required

Last-update timestamp. Like created_ts, this is the recipient-specific *_ts field rather than the updated_at used elsewhere.

first_name
string

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
string

Middle name (individual recipients), when provided. ASCII-normalized on write.

last_name
string

Family name (individual recipients). ASCII-normalized on write.

company_name
string

Legal company name (business recipients).

phone
string

Contact phone for the recipient, when provided.

email
string

Contact email for the recipient, when provided.

address

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.

metadata
object

Your own key/value string pairs attached to the recipient.