Skip to main content
GET
/
whatsapp
/
contacts
List contacts
curl --request GET \
  --url https://api.kapso.ai/platform/v1/whatsapp/contacts \
  --header 'X-API-Key: <api-key>'
{ "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "wa_id": "15551234567", "profile_name": "John Doe", "display_name": "John (VIP)", "customer_id": "550e8400-e29b-41d4-a716-446655440000", "metadata": { "segment": "vip" }, "created_at": "2025-03-26T15:05:00.000000Z", "updated_at": "2025-03-26T15:05:00.000000Z" }, { "id": "223e4567-e89b-12d3-a456-426614174001", "wa_id": "15557654321", "profile_name": "Jane Smith", "display_name": null, "customer_id": null, "metadata": { "source": "sandbox" }, "created_at": "2025-03-26T15:00:00.000000Z", "updated_at": "2025-03-26T15:00:00.000000Z" } ], "meta": { "page": 1, "per_page": 20, "total_pages": 1, "total_count": 2 } }

Documentation Index

Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
customer_id
string

Filter by associated customer ID

​
customer_external_id
string

Filter by customer external ID

​
has_customer
boolean

Filter by customer association (true/false)

​
profile_name_contains
string

Filter by profile name (case-insensitive substring match)

​
wa_id_contains
string

Filter by WhatsApp ID (substring match)

​
business_scoped_user_id
string

Filter by exact WhatsApp business-scoped user ID

​
created_after
string<date-time>

Filter contacts created after this ISO 8601 timestamp

​
created_before
string<date-time>

Filter contacts created before this ISO 8601 timestamp

​
page
integer
default:1

Page number for legacy offset pagination. Deprecated — use cursor pagination (limit, after, before) instead. Maximum page: 50. Maximum window (page × per_page): 5,000. Requests exceeding these limits return a 400 error.

Required range: x <= 50
​
per_page
integer
default:20

Items per page for legacy offset pagination.

Required range: x <= 100
​
limit
integer
default:20

Maximum number of results per cursor-paginated page (default 20, max 100).

Required range: 1 <= x <= 100
​
before
string

Cursor for the previous page (Base64 encoded).

​
after
string

Cursor for the next page (Base64 encoded).

Response

Successfully retrieved contacts

​
data
object[]
required
​
meta
object
​
paging
object