List contacts in one contact book with pagination and search.
Get Contacts
Summary
List contacts in one contact book with pagination and search.
Prerequisites
- Authorization: Bearer w91_live_xxx
- Content-Type: application/json for JSON requests
Related documentation
Endpoint: GET /api/v2/contact-books/{bookUid}/contacts. Use this API to inspect the contacts linked to a specific contact book.
GET
/api/v2/contact-books/{bookUid}/contacts| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | header | Required | Bearer w91_public_token_here. Must be a global public API token. |
bookUid | string | Required | Contact book UID, for example grp_abc. |
page | number | Optional | Positive integer page number. Default 1. |
limit | number | Optional | Page size for pagination. Default 50. |
search | string | Optional | Search by phone, display name, email, or company details. |
List contacts in a book
curl -X GET "https://graph.whats91.com/api/v2/contact-books/grp_abc/contacts?page=1&limit=50&search=asha" \
-H "Authorization: Bearer w91_public_token_here"Contacts response
{
"success": true,
"message": "Contact book contacts retrieved",
"data": {
"contactBook": {
"contactBookUid": "grp_abc",
"name": "Retail Leads"
},
"contacts": [
{
"contactUid": "ct_abc",
"uid": "ct_abc",
"phone": "917000782082",
"phoneE164": "917000782082",
"displayName": "Asha Rao",
"email": "asha@example.com",
"companyName": "Acme",
"status": "ACTIVE",
"groups": [{ "uid": "grp_abc", "name": "Retail Leads", "status": "ACTIVE" }],
"customFields": { "city": "Mumbai" }
}
],
"items": [
{
"contactUid": "ct_abc",
"uid": "ct_abc",
"phone": "917000782082",
"displayName": "Asha Rao"
}
],
"pagination": {
"page": 1,
"limit": 50,
"count": 1,
"hasMore": false
}
}
}Internal database IDs, user_id, and admin_id are never returned by public v2 contact book APIs.
| Field | Meaning |
|---|---|
| phoneE164 | Normalized WhatsApp-ready phone number. |
| displayName | Readable contact name for dashboards and campaign previews. |
| email and companyName | Optional enrichment fields stored with the contact. |
| groups | Contact book memberships returned as public UIDs and names. |
| customFields | Developer-defined key-value metadata such as city, source, or segment. |
SDK Examples
Use these examples as starting points for server-side implementations.
cURL
curl -X GET "https://graph.whats91.com/api/v2/contact-books/{bookUid}/contacts" \
-H "Authorization: Bearer w91_live_xxx"Node.js
const response = await fetch("https://graph.whats91.com/api/v2/contact-books/{bookUid}/contacts", {
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/{bookUid}/contacts");
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/{bookUid}/contacts",
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/{bookUid}/contacts");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());