Address Book Contacts

Fetch all contacts inside a specific address book. Results are paginated — 100 per page by default.

Endpoint

POST /v1/address-books/contacts/

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 Body

{
  "id": 1
}

Field	Type	Required	Description
`id`	integer	Yes	Address book ID from the Address Books endpoint

Response

200 OK

{
  "address_book": {
    "id": 1,
    "name": "Premium Customers"
  },
  "total": 342,
  "page": 1,
  "page_size": 100,
  "total_pages": 4,
  "next": "https://api.talkntalk.africa/v1/address-books/contacts/?page=2&page_size=100",
  "previous": null,
  "results": [
    {
      "id": 101,
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+254700000001",
      "email": "jane@example.com",
      "notes": "",
      "created_at": "2026-03-01T10:00:00+00:00"
    },
    {
      "id": 102,
      "first_name": "John",
      "last_name": "Mwangi",
      "phone": "+254711000002",
      "email": "",
      "notes": "VIP",
      "created_at": "2026-03-05T08:30:00+00:00"
    }
  ]
}

Field	Type	Description
`address_book.id`	integer	The address book ID
`address_book.name`	string	The address book name
`total`	integer	Total contacts 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	Contact ID
`results[].first_name`	string	First name (may be empty)
`results[].last_name`	string	Last name (may be empty)
`results[].phone`	string	Phone number in E.164 format
`results[].email`	string	Email address (may be empty)
`results[].notes`	string	Optional notes
`results[].created_at`	string (ISO 8601)	When the contact was added

Code Examples

curl -X POST "https://api.talkntalk.africa/v1/address-books/contacts/?page=1&page_size=100" \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

Error Responses

Status	Meaning
`400 Bad Request`	`id` field missing from request body
`401 Unauthorized`	Missing or invalid API key
`404 Not Found`	Address book does not exist or does not belong to your organisation

{
  "detail": "Field 'id' is required."
}

{
  "detail": "Address book not found."
}

Address Books Overview