Register who is being paid

post

https://api.avvio.xyz/business/api/v1/recipients/{orgId}

method.recipientDetails carries the corridor's fields, exactly as
named by GET /corridors.

Two separate protections, and they do different jobs:
Idempotency-Key makes a retry safe; externalId makes a repeat
safe by returning the existing beneficiary instead of registering a
second bank account. Send both.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

orgId

string

required

length ≥ 1

The opaque organization id issued to you, normally CUID-shaped (for
example cmsx…). It is not an org_-prefixed alias. Pass it unchanged
in every organization-scoped path.

Body Params

type

string

enum

required

Allowed:

name

string

required

length ≥ 1

string

required

phone

string

Optional phone number as text, including any international prefix.

country

string

length between 2 and 2

^[A-Za-z]{2}$

ISO-3166 alpha-2.

externalId

string

length between 1 and 128

Your id for this beneficiary. Sending it makes creation repeat-safe:
the same value returns the existing beneficiary rather than
registering a second bank account.

endUserId

string

length between 1 and 128

Your id for the person SENDING. Scopes the beneficiary to them.
Omit it and the beneficiary is visible to every one of your users.

method

required

Headers

Idempotency-Key

string

required

length between 1 and 255

^[A-Za-z0-9_.:-]+$

A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.

Reuse it to retry. Same key with the same body replays the stored
response; same key with a different body is a 409, because
answering with the first call's result would hand you a receipt for a
payout you did not request. A 4xx releases the key, so you can fix the
body and reuse it.

Reuse it — do not generate one per attempt. A key minted per attempt
defeats replay entirely: every retry looks like a new request, so every
retry pays. We also watch for an identical body arriving under a
different key within 15 minutes and refuse it with
DUPLICATE_REQUEST_DETECTED.

Records are kept for 7 days. That is a retention window, not a
correctness one — there is no path where an expired key is re-executed.

Responses

201Created, or the existing beneficiary for this externalId

400Validation failed, or a corridor field is missing

401Missing, invalid, or revoked key — or a key on a route that does not accept one.

403Valid key, wrong organization.

409Either this bank account is already linked to another beneficiary, or the idempotency key was reused with a different body.