# Add to the address book

Product: Direct Trade API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/direct-trade-api/integration-guide/add-to-address-book

Add each owned external bank account or wallet to your address book before
using it to send funds into Axiym or receive funds from Axiym. The account
must belong to your company.

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

## 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 ownership checks, review outcomes, and lifecycle
transitions are available in sandbox. See
[Sandbox testing](/direct-trade-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.

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/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/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:

* 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 entry starts in `PENDING_REVIEW`. Retrieve it until it becomes `ACTIVE`:

```sh
curl \
  "https://partner-api.sandbox.axiym.io/api/v1/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 address book entry, Axiym account, deposit, and withdrawal all belong to
your company throughout the workflow.