Skip to main content
POST
Add an Address to a Payee

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

payee_id
string<uuid>
required

Query Parameters

user_id
string<uuid>
required

The unique ID of the user who owns this payee.

Example:

"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"

Body

application/json

Create a payee address.

country (ISO 3166-1 alpha-2) is required — it is the key an international payout matches against the resolved destination country, so an address with no country could never be used for one. line1 is required too: a saved "address" with no street is not usable for a mailed check or a payout's beneficiary block.

line1
string
required

Street and number.

Maximum string length: 255
country
string
required

ISO 3166-1 alpha-2 country code, e.g. MX, IN, AE.

purposes
string[]
required

Which of your enabled products this address may be used for (e.g. document_mailing, international). At least one is required — fetch the allowed set from GET .../payees/address-purposes.

Minimum array length: 1
label
string | null
Maximum string length: 120
address_type
string | null
Maximum string length: 30
line2
string | null
Maximum string length: 255
city
string | null
Maximum string length: 120
state
string | null
Maximum string length: 120
postal_code
string | null
Maximum string length: 20
phone
string | null
Maximum string length: 40
doc_number
string | null
Maximum string length: 100
doc_type
string | null
Maximum string length: 50
doc_issue_country
string | null
Maximum string length: 10
doc_issue_date
string | null
Maximum string length: 20
doc_due_date
string | null
Maximum string length: 20
doc_issuer
string | null
Maximum string length: 255
is_default
boolean
default:false
on_international_conflict
enum<string> | null

Only meaningful when purposes includes international and this payee already has a different address for the same country tagged international — at most one address per (payee, country) may carry that purpose. Omit on the first attempt: if a conflict exists the request is rejected with international_address_conflict naming the existing address, and you resubmit with this field set. replace drops the international purpose from the existing address (revoking it entirely if that was its only purpose) and gives it to this one. keep leaves the existing address untouched and saves this one for its other purposes only — international is dropped from this address's purposes, so at least one other purpose must be selected or the request is rejected.

Available options:
replace,
keep

Response

Successful Response

status_code
integer
required

HTTP status code for the response.

data
PayeeAddressRead · object
required

Payload or error details.

query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.