How do I list contact books?
Use GET /api/v2/contact-books with pagination to retrieve the customer account contact books.
List account-wide Whats91 contact books with pagination and filters.
List Contact Books
Summary
Use Contact Book APIs to list books, inspect contacts, create or update books, and upload JSON contact batches.
Prerequisites
- Bearer token authentication
- A global customer-level API token for contact book management
Related documentation
Endpoint: GET /api/v2/contact-books. Whats91 exposes public contact book management through /api/v2/contact-books only. Contact books are customer-account-wide resources and require a global public API token.
Number-scoped public API tokens cannot access contact books. They return TOKEN_SCOPE_NOT_ALLOWED because contact books are not tied to one WhatsApp sender number.
GET
/api/v2/contact-books| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | header | Required | Bearer w91_public_token_here. Must be a global public API token. |
page | number | Optional | Positive integer page number. Default 1. |
limit | number | Optional | Page size for pagination. Default 50. |
status | string | Optional | Filter by ACTIVE or INACTIVE contact book status. |
search | string | Optional | Search by contact book name or description. |
List contact books
curl -X GET "https://graph.whats91.com/api/v2/contact-books?page=1&limit=50&status=ACTIVE&search=retail" \
-H "Authorization: Bearer w91_public_token_here"List response
{
"success": true,
"message": "Contact books retrieved",
"data": {
"contactBooks": [
{
"contactBookUid": "grp_abc",
"uid": "grp_abc",
"name": "Retail Leads",
"description": "Retail campaign contacts",
"color": "#0f62fe",
"status": "ACTIVE",
"contactCount": 120,
"createdAt": "2026-06-06T08:00:00.000Z",
"updatedAt": "2026-06-06T08:00:00.000Z"
}
],
"items": [
{
"contactBookUid": "grp_abc",
"uid": "grp_abc",
"name": "Retail Leads",
"status": "ACTIVE",
"contactCount": 120
}
],
"pagination": {
"page": 1,
"limit": 50,
"count": 1,
"hasMore": false
}
},
"metadata": {
"apiVersion": "v2",
"requestId": "request-uuid"
}
}items is an alias of contactBooks for generic paginated clients. List endpoints return empty arrays when no rows match.
| Filter | Accepted values | Use case |
|---|---|---|
| page and limit | Positive integers | Move through paginated contact book results. |
| status | ACTIVE, INACTIVE | Separate active lists from archived or disabled books. |
| search | Any search string | Find books such as Retail Leads, VIP Buyers, or Trial Users. |
SDK Examples
Use these examples as starting points for server-side implementations.
cURL
curl -X GET "https://graph.whats91.com/api/v2/contact-books" \
-H "Authorization: Bearer w91_live_xxx"Node.js
const response = await fetch("https://graph.whats91.com/api/v2/contact-books", {
method: "GET",
headers: {
"Authorization": "Bearer w91_live_xxx",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data);PHP
$ch = curl_init("https://graph.whats91.com/api/v2/contact-books");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer w91_live_xxx",
"Content-Type: application/json"
]
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Python
import requests
response = requests.request(
"GET",
"https://graph.whats91.com/api/v2/contact-books",
headers={
"Authorization": "Bearer w91_live_xxx",
"Content-Type": "application/json",
}
)
print(response.json())C#
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer w91_live_xxx");
var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.whats91.com/api/v2/contact-books");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Frequently Asked Questions
Can I upload contacts in bulk?
Yes. Use the JSON bulk upload endpoint with an array of contact rows and supported custom fields.
Are contact books sender-specific?
Contact books are customer-account-wide resources used by messaging and campaign workflows.
Related APIs
Get Contacts
List contacts in one contact book with pagination and search.
Upload Contacts
Bulk upload contacts into one contact book using a JSON payload.
Template Send
Send approved WhatsApp templates with Whats91-specific fields, aliases, media headers, and button parameters.
Blacklist
List sender-scoped message blacklist entries for a WhatsApp registered sender.