# Add to the address book

Product: Client Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.sandbox.axiym.io/client-account-api/integration-guide/add-to-address-book

Register each external bank account or wallet in the selected client’s address book for
whitelisting before using it to fund deposits or receive withdrawals. Axiym
performs due diligence and compliance checks before it becomes `ACTIVE`.

Each entry returns a `destinationId`. Despite the identifier name, an entry is
required for both deposits and withdrawals.

Use `/clients/{clientId}/address-book` for the selected client. Keep the
address book entry and the receiving or source Axiym account in the same
client context.

## Testing in sandbox

Use only bank details, wallet addresses, blockchain networks, and test assets
provided or approved for your sandbox environment. Never add production
payment details for a sandbox test.

Confirm with Axiym which due diligence and compliance checks, review outcomes, and lifecycle
transitions are available in sandbox. See
[Sandbox testing](/client-account-api/integration-guide/sandbox-testing).

## 1. Add a bank account or wallet

Add a bank account using the details agreed for your sandbox. Replace the
illustrative bank values below before sending the request.

Supply exactly one of `iban` or `accountNumber`, together with `currency` and
the `bank` details. Use `iban` for an account identified by an IBAN, or
`accountNumber` for a domestic account number. The `bank` object requires
`bankName` and `address.country`.

Bank fields depend on the destination corridor: supply `swiftBic` when
required, and `clearingCode` for a required local routing code. Supply
`clearingSystemCode` where the country has more than one clearing system.
Omit unused optional fields instead of sending empty strings.

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/bank-accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data '{
    "currency": "USD",
    "accountNumber": "0123456789",
    "bank": {
      "bankName": "Bank of America",
      "address": { "country": "US" },
      "swiftBic": "BOFAUS3NXXX"
    }
  }'
```

Or add a wallet address:

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/wallets" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REGISTER_IDEMPOTENCY_KEY" \
  --data "{\
    \"currency\": \"$EXTERNAL_ACCOUNT_CURRENCY\",\
    \"walletAddress\": \"$TESTNET_WALLET_ADDRESS\",\
    \"network\": \"$BLOCKCHAIN_NETWORK\"\
  }"
```

Use a different idempotency key for each new entry. Reuse the original key
only when retrying the same request after an ambiguous result.

## 2. Store the entry

Store the returned `destinationId` with:

* the `clientId` whose address book contains it;
* whether it is a bank account or wallet;
* its currency and blockchain network where applicable; and
* its current status.

Do not store `destinationId` as an Axiym `accountId`. The identifiers represent
different resources and are not interchangeable.

## 3. Wait for activation

A new external account starts in `PENDING_REVIEW` while Axiym performs due
diligence and compliance checks. Once approved, it becomes `ACTIVE` and is
whitelisted for deposits and withdrawals. Retrieve the entry to check its status:

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/clients/$CLIENT_ID/address-book/$DESTINATION_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"
```

Use `destination.*` events to react to lifecycle changes, and fetch the entry
when your workflow needs its current status. Only `ACTIVE` entries may be used.
`destination.closed` signals that the entry is permanently retired and can no
longer fund deposits or receive withdrawals.

## 4. Use the entry in the correct direction

* **Deposit:** initiate the bank or blockchain payment from the exact account
  or wallet in the entry. Deposit instructions separately identify where the
  payment must be sent.
* **Withdrawal:** pass the entry's `destinationId` when creating the
  withdrawal.

The returned `destinationId` identifies the external account’s entry in the
selected client’s address book.