Update an Address

Update an address

curl --request PATCH \
  --url https://api.brale.xyz/accounts/{account_id}/addresses/{address_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "date_of_birth": "1990-01-31"
}
'

import requests

url = "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}"

payload = { "date_of_birth": "1990-01-31" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({date_of_birth: '1990-01-31'})
};

fetch('https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'date_of_birth' => '1990-01-31'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}"

	payload := strings.NewReader("{\n  \"date_of_birth\": \"1990-01-31\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"date_of_birth\": \"1990-01-31\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"date_of_birth\": \"1990-01-31\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
  "status": "active",
  "name": "Solana Custodial Wallet",
  "address": "73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me",
  "transfer_types": [
    "solana",
    "base",
    "wire"
  ]
}

{
  "type": "date_of_birth_already_set",
  "detail": "Date of birth is already set and cannot be changed",
  "code": "ValidationError",
  "status": 400
}

{
  "type": "recipient_update_failed",
  "detail": "The recipient could not be updated",
  "code": "ValidationError",
  "status": 422
}

PATCH

accounts

{account_id}

addresses

{address_id}

Update an address

curl --request PATCH \
  --url https://api.brale.xyz/accounts/{account_id}/addresses/{address_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "date_of_birth": "1990-01-31"
}
'

import requests

url = "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}"

payload = { "date_of_birth": "1990-01-31" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({date_of_birth: '1990-01-31'})
};

fetch('https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'date_of_birth' => '1990-01-31'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}"

	payload := strings.NewReader("{\n  \"date_of_birth\": \"1990-01-31\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"date_of_birth\": \"1990-01-31\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"date_of_birth\": \"1990-01-31\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
  "status": "active",
  "name": "Solana Custodial Wallet",
  "address": "73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me",
  "transfer_types": [
    "solana",
    "base",
    "wire"
  ]
}

{
  "type": "date_of_birth_already_set",
  "detail": "Date of birth is already set and cannot be changed",
  "code": "ValidationError",
  "status": 400
}

{
  "type": "recipient_update_failed",
  "detail": "The recipient could not be updated",
  "code": "ValidationError",
  "status": 422
}

Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel. This endpoint lets you make targeted updates to an existing address. All fields are optional — only include what you want to change. Endpoint

PATCH https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}

Updatable fields

Field	Type	Description
`name`	string	Rename the address.
`status`	string	`"archived"` to archive, `"active"` to unarchive (external addresses only — custodial addresses cannot be unarchived).
`additional_transfer_types`	array of strings	Add new rails to the address (e.g. `"wire"`, `"fednow_credit"`, `"solana"`). For bank addresses, supply `bank_address` and `beneficiary_address` before adding `wire`.
`bank_address`	object	Street address of the bank. Required for bank addresses before enabling wire.
`beneficiary_address`	object	Street address of the beneficiary. Required for bank addresses before enabling wire.
`account_holder_type`	string	Bank addresses only. `"individual"` or `"business"`. Can be set only while it is not set yet. Sending the value that is already stored succeeds with no change; a different value returns `400` `account_holder_type_already_set`.
`date_of_birth`	string	Bank addresses only. Individual recipient’s date of birth in `YYYY-MM-DD` format. Can be set only while no date of birth is stored. Sending the stored value succeeds with no change. A different value returns `400` `date_of_birth_already_set`.

Add transfer types to an existing address

To add new rails to an existing address (for example, adding ach_credit and same_day_ach_credit to an address), send a PATCH to the same endpoint with additional_transfer_types:

PATCH https://api.brale.xyz/accounts/{account_id}/addresses/{address_id}

Request

{
  "additional_transfer_types": ["ach_credit", "same_day_ach_credit"]
}

additional_transfer_types is merged into the address’s existing transfer_types. You do not need to resend the full existing list — send only the rails you want to add. Sending a transfer type that is already enabled is idempotent.

Add FedNow to an existing recipient

To send FedNow payouts to an existing bank address, such as an ACH recipient, add fednow_credit:

Request

{
  "additional_transfer_types": ["fednow_credit"]
}

An address with ["ach_credit"] becomes ["ach_credit", "fednow_credit"]. The address id does not change, so existing references keep working. bank_address and beneficiary_address are not required to add fednow_credit. Confirm fednow_credit is present before sending a payout. See Send FedNow payouts.

Set the account holder type

For bank addresses created without account_holder_type, set it once:

Request

{ "account_holder_type": "individual" }

It determines the ACH SEC code for payouts to this address (individual → PPD, business → CCD). Once set, it cannot be changed through the API.

Set the recipient’s date of birth

For individual bank recipients created without a date of birth, set it once:

Request

{ "date_of_birth": "1990-01-31" }

The date must be in YYYY-MM-DD format and in the past. Otherwise Brale returns 400 validation_errors. The error response does not include the submitted value.
Business recipients do not accept date_of_birth. Sending it for a business recipient returns 400 date_of_birth_not_supported. Setting account_holder_type to business on an address with a stored date of birth returns the same error.
If Brale cannot update the recipient, it does not save the date of birth. Brale returns 422 recipient_update_failed, or 503 when the update is temporarily unavailable.
Responses return date_of_birth masked to the year (for example, "1990-**-**").

Error responses

400 — invalid or incompatible transfer types, attempting to archive a pending address, attempting to unarchive a custodial address, invalid status value, or invalid account_holder_type value.
400 account_holder_type_already_set — the address already has a different account_holder_type.
400 date_of_birth_already_set — the address already has a different date_of_birth.
400 date_of_birth_not_supported — date_of_birth was sent for a business recipient, or account_holder_type: business was sent for an address with a stored date of birth.
404 — address not found or not owned by the account.
422 fednow_routing_number_not_supported — the address’s routing number does not participate in FedNow. Do not retry.
422 fednow_provider_registration_failed — FedNow registration failed. This can be temporary. Retry the same request after a backoff.
422 recipient_update_failed — Brale could not update the recipient with the new date of birth. The change is not saved.
503 — the recipient update is temporarily unavailable. The change is not saved. Retry after a backoff.

Required scope: addresses:write

Authorizations

Authorization

string

header

required

Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer " header.

Path Parameters

account_id

string<ksuid>

required

The ID of the account

Pattern: ^[a-zA-Z0-9]{27}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

address_id

string<ksuid>

required

The ID of the address

Pattern: ^[a-zA-Z0-9]{27}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

Body

application/json

name

string | null

Example:

"Company External EVM Address"

status

enum<string> | null

Available options:

active,

archived

additional_transfer_types

string[]

Transfer types to add to the address. Merged into the existing transfer_types.

bank_address

USStreetAddress · object | null

For bank addresses only. Supply before adding wire to additional_transfer_types.

Show child attributes

beneficiary_address

USStreetAddress · object | null

For bank addresses only. Supply before adding wire to additional_transfer_types.

Show child attributes

account_holder_type

enum<string>

For bank addresses only. Whether the bank account belongs to an individual or a business. Can be set only while it is not set yet. Sending the stored value succeeds with no change. A different value returns 400 account_holder_type_already_set.

Available options:

individual,

business

date_of_birth

string<date>

For bank addresses only. Date of birth of an individual recipient, in YYYY-MM-DD format. Can be set only while no date of birth is stored. Sending the stored value returns 200 with no change. A different value returns 400 date_of_birth_already_set. Sending it for a business recipient, or with account_holder_type: business, returns 400 date_of_birth_not_supported. A malformed or future date returns 400 validation_errors. Responses return the date masked to the year (1990-**-**).

Example:

"1990-01-31"

Response

The updated address

string<ksuid>

Pattern: ^[a-zA-Z0-9]{27}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

status

enum<string>

Available options:

pending,

active,

archived

Example:

"active"

name

string

Example:

"Solana Custodial Wallet"

address

string

The on-chain wallet address

Example:

"73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me"

transfer_types

string[]

Example:

["solana", "base", "wire"]

API overview

Accounts

Addresses

Automations (virtual accounts)

Transfers

Financial institutions

Webhooks

Tokenization

Update an Address

Updatable fields

Add transfer types to an existing address

Add FedNow to an existing recipient

Set the account holder type

Set the recipient’s date of birth

Error responses

Authorizations

Path Parameters

Body

Response