---
sidebar_position: 4
title: Address Books
description: Organize contacts into named address books — create, update, and delete address books via the Firetell Agent API.
---

# Address Books

Organize your [Contacts](/docs/rest-api/agent-api/contacts) into named address books for better management. Address books act as folders — **every contact must belong to an address book**. 

When a new workspace is created, a system address book named **`Default`** is automatically initialized. If a contact is created without specifying an `address_book_id`, it is automatically assigned to the `Default` address book.

## Endpoints

| Method   | Endpoint                             | Description               |
| -------- | ------------------------------------ | ------------------------- |
| `GET`    | `/call-center/address-books`         | List all address books    |
| `GET`    | `/call-center/address-books/:id`     | Get address book details  |
| `POST`   | `/call-center/address-books`         | Create a new address book |
| `PUT`    | `/call-center/address-books/:id`     | Update an address book    |
| `DELETE` | `/call-center/address-books/:id`     | Delete an address book    |

## Authentication

All endpoints require `Bearer` JWT with `agent-api` audience.

## Address Book Object

| Field          | Type    | Description                                                            |
| -------------- | ------- | ---------------------------------------------------------------------- |
| `id`           | string  | Unique address book ID (prefixed `ab_`)                                |
| `workspace_id` | string  | Workspace identifier                                                   |
| `title`        | string  | Address book name                                                      |
| `description`  | string  | Optional description                                                   |
| `is_default`   | boolean | Whether this is the system default address book (cannot be deleted/modified) |
| `owner_id`     | string  | ID of the owning agent or team (null for `everyone`)                   |
| `owner_type`   | string  | Ownership scope: `agent`, `team`, or `everyone`                        |
| `created_at`   | string  | ISO 8601 creation timestamp                                            |
| `updated_at`   | string  | ISO 8601 last update timestamp                                         |

---

## List All Address Books

```
GET /call-center/address-books
```

Retrieve a paginated list of all address books accessible to the current agent.

### Query Parameters

| Parameter    | Type   | Default | Description                       |
| ------------ | ------ | ------- | --------------------------------- |
| `page`       | number | `1`     | Page number (min: 1)              |
| `limit`      | number | `20`    | Items per page (min: 1, max: 100) |
| `search`     | string | —       | Search by title (text search)     |
| `sort_field` | string | —       | Sort by: `created_at`, `title`    |
| `sort_order` | string | `desc`  | Sort order: `asc` or `desc`       |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/address-books?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "ab_x1y2z3w4v5u6t7s8",
      "workspace_id": "my_workspace",
      "title": "VIP Customers",
      "description": "High-value customers with active contracts",
      "created_at": "2026-01-10T10:00:00.000Z",
      "updated_at": "2026-07-01T12:00:00.000Z"
    },
    {
      "id": "ab_a9b8c7d6e5f4g3h2",
      "workspace_id": "my_workspace",
      "title": "Leads Q3 2026",
      "description": null,
      "created_at": "2026-07-01T08:00:00.000Z",
      "updated_at": "2026-07-01T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

---

## Get Address Book Details

```
GET /call-center/address-books/:id
```

Retrieve detailed information about a specific address book.

### Path Parameters

| Parameter | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| `id`      | string | Address book ID (e.g., `ab_x1y2...`)  |

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/address-books/ab_x1y2z3w4v5u6t7s8" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

Returns the full address book object.

### Error Responses

| Status | Description             |
| ------ | ----------------------- |
| `404`  | Address book not found  |

---

## Create an Address Book

```
POST /call-center/address-books
```

Create a new address book in the workspace.

### Request Body

| Field         | Type   | Required | Description                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `title`       | string | ✅       | Address book name (1–100 characters)                                |
| `description` | string |          | Optional description (max 500 chars)                                |
| `owner_type`  | string |          | Ownership scope: `agent`, `team`, or `everyone` (defaults to `agent` in Agent API) |
| `owner_id`    | string |          | ID of the owning team (required if `owner_type` is `team`). Automatically assigned to your agent ID if `owner_type` is `agent`. |

### Request

```bash
curl -X POST "https://{workspace_id}.firetell.app/api/v1/call-center/address-books" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Enterprise Clients",
    "description": "Contacts from enterprise accounts with dedicated support",
    "owner_type": "team",
    "owner_id": "tm_sales123"
  }'
```

### Response `201 Created`

```json
{
  "id": "ab_n3w1d2e3f4g5h6i7",
  "workspace_id": "my_workspace",
  "title": "Enterprise Clients",
  "description": "Contacts from enterprise accounts with dedicated support",
  "is_default": false,
  "owner_type": "team",
  "owner_id": "tm_sales123",
  "created_at": "2026-07-21T08:00:00.000Z",
  "updated_at": "2026-07-21T08:00:00.000Z"
}
```

### Error Responses

| Status | Description                                                                 |
| ------ | --------------------------------------------------------------------------- |
| `400`  | Validation error                                                            |
| `403`  | Forbidden — Only leaders can create address books for a team or `everyone`  |

---

## Update an Address Book

```
PUT /call-center/address-books/:id
```

Update an existing address book's title, description, or ownership settings.

### Path Parameters

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `id`      | string | Address book ID  |

### Request Body

| Field         | Type   | Required | Description                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------- |
| `title`       | string |          | Updated name (1–100 characters)                                     |
| `description` | string |          | Updated description (max 500 chars)                                 |
| `owner_type`  | string |          | Ownership scope: `agent`, `team`, or `everyone`                     |
| `owner_id`    | string |          | ID of the owning agent or team                                      |

### Request

```bash
curl -X PUT "https://{workspace_id}.firetell.app/api/v1/call-center/address-books/ab_x1y2z3w4v5u6t7s8" \
  -H "Authorization: Bearer YOUR_AGENT_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VIP Customers 2026",
    "description": "Updated address book for active VIP accounts in 2026",
    "owner_type": "team",
    "owner_id": "tm_support456"
  }'
```

### Response `200 OK`

Returns the updated address book object.

### Error Responses

| Status | Description                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `400`  | Validation error or attempting to modify `Default` address book                                         |
| `403`  | Forbidden — Only leaders can modify team/shared address books, or attempting to modify another agent's book |
| `404`  | Address book not found                                                                                  |

---

## Delete an Address Book

```
DELETE /call-center/address-books/:id
```

Permanently delete an address book. Contacts that belong to this book are **not deleted** — they are automatically reassigned to the system **`Default`** address book instead.

### Path Parameters

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `id`      | string | Address book ID  |

### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/call-center/address-books/ab_x1y2z3w4v5u6t7s8" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

Returns the deleted address book object.

### Error Responses

| Status | Description                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `400`  | Cannot delete system `Default` address book                                                             |
| `403`  | Forbidden — Only leaders can delete team/shared address books, or attempting to delete another agent's book |
| `404`  | Address book not found                                                                                  |

:::info
When a custom address book is deleted, all contacts that belonged to it will be automatically reassigned to the system **`Default`** address book. The contacts themselves are preserved.
:::