---
title: "List contacts"
method: GET
path: "/whatsapp/contacts"
tags: ["Contacts"]
---

# List contacts

`GET /whatsapp/contacts`

Retrieve a paginated list of WhatsApp contacts for your project.

## Query parameters

- `customer_id` string
- `customer_external_id` string
- `has_customer` boolean
- `profile_name_contains` string
- `wa_id_contains` string
- `business_scoped_user_id` string
- `created_after` string, date-time
- `created_before` string, date-time
- `page` integer
- `per_page` integer
- `limit` integer
- `before` string
- `after` string

## Response `200`

Successfully retrieved contacts

- WhatsappContactListResponse
  - `data` WhatsappContact[], required
    - `id` string, uuid — Unique contact ID
    - `wa_id` string, nullable — WhatsApp ID (E.164 phone number). Can be null when Meta only provides BSUID-based identity.
    - `business_scoped_user_id` string, nullable — WhatsApp business-scoped user ID
    - `parent_business_scoped_user_id` string, nullable — Parent business-scoped user ID when provided by Meta
    - `username` string, nullable — WhatsApp username when available
    - `profile_name` string — Name as shown on WhatsApp
    - `display_name` string, nullable — Custom display name set by your app
    - `customer_id` string, uuid, nullable — Associated customer ID
    - `metadata` object, nullable — Custom key-value data
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `meta` PaginationMeta
    - `page` integer, required
    - `per_page` integer, required
    - `total_pages` integer, required
    - `total_count` integer, required
  - `paging` Paging
    - `cursors` PaginationCursor
      - `before` string — Cursor for previous page (Base64 encoded)
      - `after` string — Cursor for next page (Base64 encoded)
    - `next` string, nullable
    - `previous` string, nullable

## Other responses

- `400` — Legacy pagination limit exceeded
- `401` — Unauthorized

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)