# Change an Address Book Entry

Its label, tags and reference change at once. A new address cools again before it is a destination.

## Overview

- **`label`, `tags`, `customerRefId`** (`null` clears it): changed at once; the status stays.
- **A new address** — `address`, `network` or `chain` on an external or contract entry, `walletId` on an internal one — is the entry's next `version`, unproven: it cools again from this request (`cooling` until the new `activeAt`, or `active` with a cooling period of 0) — or, an external address your settings require to be proven, waits in `pending_approval` for its proof —, and you become who asked. A contract's code is checked again. Sending the values it already has changes nothing.
- `kind`, `family` and `accountId` never change: add another entry. A body with nothing to change answers `400` `ADDRESS_BOOK_REQUEST_INVALID` (`(body): nothing to change`).
- `200` with the entry. A rejected or removed entry answers `409` `ADDRESS_BOOK_ENTRY_FINAL`; an address another live entry holds, `409` `ADDRESS_BOOK_ENTRY_EXISTS`; an entry changed by someone else meanwhile, `409` `ADDRESS_BOOK_ENTRY_CHANGED` — send it again. The address refusals are those of [Add an Entry](https://docs.aureahub.com/docs/address-book-entry-add.md).
- For `owner`, `tenantadmin`, `non_signing_admin` and `editor`.

## Endpoint

### `PATCH /v1/address-book/entries/{entryId}`

Authentication: bearer token required.

Changes an entry; a new address cools again from this request.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `entryId` | string (uuid) | yes | The entry's id |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | no | 1–100 characters, no space at either end |
| `tags` | string[] | no | The new tags, up to 20 |
| `customerRefId` | string \| null | no | Your reference; `null` clears it |
| `address` | string | no | External or contract: a new address |
| `network` | string | no | External or contract: `mainnet` or `testnet` |
| `chain` | string \| null | no | External or contract: a chain's slug; `null`: every chain of the family |
| `walletId` | string (uuid) | no | Internal: another of your wallets |

**Responses**

`200` Address changed

```json
{
  "id": "8f3c2a71-5d4e-4b9a-a6c1-2e7f9d0b3c58",
  "accountId": null,
  "kind": "external",
  "family": "evm",
  "network": "mainnet",
  "chain": null,
  "chainId": null,
  "address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
  "walletId": null,
  "label": "Supplier payouts",
  "tags": ["suppliers"],
  "customerRefId": "SUP-0042",
  "status": "cooling",
  "version": 2,
  "requestedBy": "0d2f6b8a-4c1e-4a93-b7d5-2e9f1c3a8b60",
  "requestedScope": "tenant",
  "requestedAt": "2026-10-10T09:41:07.000Z",
  "approval": {
    "approvedBy": null,
    "approvedScope": "tenant",
    "approvedAt": "2026-10-10T09:41:07.000Z",
    "requiredApprovals": 0
  },
  "coolingPeriodSeconds": 86400,
  "activeAt": "2026-10-11T09:41:07.000Z",
  "coolingSecondsLeft": 86400,
  "proof": { "proven": false, "method": null, "provenAt": null },
  "rejectedBy": null,
  "rejectedAt": null,
  "removedBy": null,
  "removedAt": null,
  "createdAt": "2026-10-08T08:00:12.000Z",
  "updatedAt": "2026-10-10T09:41:07.000Z"
}
```

`409` Final

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "A removed entry never changes again",
  "details": { "code": "ADDRESS_BOOK_ENTRY_FINAL", "status": "removed" }
}
```

**Example request**

```bash
curl -X PATCH https://api.aureahub.com/v1/address-book/entries/$ENTRY_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["suppliers", "eu"] }'
```

---

Web version: https://docs.aureahub.com/#address-book-entry-change