Address Books
List all address books (contact groups) belonging to your organisation. Results are paginated — 100 per page by default.
Endpoint
GET /v1/address-books/Authentication: Bearer API key
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
page_size | integer | 100 | Results per page (max 500) |
Request
curl "https://api.talkntalk.africa/v1/address-books/?page=1&page_size=100" \
-H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Response
200 OK
{
"total": 25,
"page": 1,
"page_size": 100,
"total_pages": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "Premium Customers",
"description": "High-value customer segment",
"contact_count": 342,
"created_at": "2026-01-10T08:00:00+00:00",
"updated_at": "2026-04-15T14:22:00+00:00"
},
{
"id": 2,
"name": "Newsletter Subscribers",
"description": "",
"contact_count": 1580,
"created_at": "2026-02-01T09:00:00+00:00",
"updated_at": "2026-05-01T11:00:00+00:00"
}
]
}| Field | Type | Description |
|---|---|---|
total | integer | Total number of address books across all pages |
page | integer | Current page number |
page_size | integer | Number of results in this page |
total_pages | integer | Total number of pages |
next | string | null | URL of the next page, or null if on the last page |
previous | string | null | URL of the previous page, or null if on the first page |
results[].id | integer | Address book ID — use this in the contacts endpoint |
results[].name | string | Address book name |
results[].description | string | Optional description |
results[].contact_count | integer | Number of contacts in this address book |
results[].created_at | string (ISO 8601) | When the address book was created |
results[].updated_at | string (ISO 8601) | When the address book was last modified |
Code Examples
curl "https://api.talkntalk.africa/v1/address-books/?page=1&page_size=100" \
-H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Error Responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing or invalid API key |
{
"detail": "Invalid or revoked API key."
}