Skip to main content
POST
/
v1
/
addressBook
/
recipients
Create a recipient
curl --request POST \
  --url https://api-sandbox.circle.com/v1/addressBook/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "chain": "ALGO",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "metadata": {
    "nickname": "sample nickname",
    "email": "satoshi@circle.com",
    "bns": "sample.circle"
  },
  "addressTag": "123456789"
}
'
{
  "data": {
    "id": "8755d0ea-14f9-4259-b092-de23c14b6568",
    "chain": "ETH",
    "address": "0x45bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "sample nickname",
      "email": "satoshi@circle.com",
      "bns": "sample.circle"
    },
    "status": "pending",
    "identity": {
      "type": "individual",
      "firstName": "Ada",
      "lastName": "Lovelace"
    },
    "createDate": "2022-07-21T20:13:35.578678Z",
    "updateDate": "2022-07-21T20:19:24.859052Z"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

For Circle entities other than CIRCLE_SG.

​
idempotencyKey
string<uuid>
required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

​
chain
enum<string>
required

Blockchain network code for the recipient address (address book scope).

Available options:
ALGO,
APTOS,
ARB,
AVAX,
BASE,
CELO,
ETH,
HBAR,
NEAR,
NOBLE,
OP,
PAH,
POLY,
SOL,
SUI,
UNI,
XLM,
XRP,
ZKS
​
address
string
required

An alphanumeric string representing a blockchain address. Formatting varies by blockchain. Be sure to preserve the exact formatting and capitalization of the address.
Important: For Ripple (XRP) addresses, only the classic address format is supported (for example, rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY).
The x-address format is NOT supported currently (for example, XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV).

Example:

"0x8381470ED67C3802402dbbFa0058E8871F017A6F"

​
metadata
object
required
​
addressTag
string | null

The secondary identifier for a blockchain address. An example of this is the memo field on the Stellar network, which can be text, id, or hash format.

Example:

"123456789"

​
identity
object

Beneficiary identity for the address book entry.

When type is individual, include firstName and lastName. When type is business, include businessName.

Related validation error codes include 2024 (identity missing), 2031–2034, and 2036 (identity cannot be updated via PATCH).

Response

Successfully created an address book recipient.

​
data
General customers · object

For Circle entities other than CIRCLE_SG.