Address Books

Organize your 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

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

{
  "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

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

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

{
  "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

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

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.