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

# List contacts

`GET /contacts`

Lists the contacts of the workspace, 25 per page.

Any query parameter other than `cursor`, `waId` and `phoneNumber` is treated as a filter on a custom contact property of the workspace — e.g. `?plan=premium` returns the contacts whose `plan` property equals `premium`.

When more results are available, `cursors.next` is returned. Pass it back as `cursor` to fetch the next page; the original filters are preserved by the cursor.

## Query parameters

- `cursor` string — Opaque cursor returned by a previous call, used to fetch the next page
- `waId` string — Filters by the WhatsApp id of the contact
- `phoneNumber` string — Filters by the phone number of the contact

## Response `200`

A page of contacts

- object
  - `data` object[], required
    - `id` string, uuid, required
    - `waId` string, nullable, required — WhatsApp id of the contact
    - `waProfileName` string, nullable, required — Name in the WhatsApp profile of the contact
    - `firstName` string, nullable, required
    - `lastName` string, nullable, required
    - `email` string, nullable, required
    - `phone` string, nullable, required
    - `occupation` string, nullable, required
    - `gender` string, nullable, required
    - `birthdate` string, nullable, required
    - `age` number, nullable, required
    - `notes` string, nullable, required
    - `tags` object[], required
      - `id` string, uuid, required
      - `name` string, required
    - `createDate` string, date-time, required
    - `updateDate` string, date-time, required
    - `customProperties` object, required — Values of the custom contact properties of the workspace, keyed by property name
  - `cursors` object
    - `next` string — Opaque cursor to fetch the next page. Absent when there are no more results

## Other responses

- `401` — Unauthorized

## Changes

- **2026-07-28** `8ccfb9a461e2` — 1 breaking, 1 info
  - api path removed without deprecation
  - endpoint added
- **2026-01-27** `e21feba47bec` — 1 info
  - added the optional property `data/items/customProperties` to the response with the `200` status
- **2026-01-21** `e345c865fde9` — 1 warning, 1 info
  - removed the optional property `data/items/cursors` from the response with the `200` status
  - added the optional property `cursors` to the response with the `200` status
- **2026-01-21** `5fbcb3c07967` — 1 info
  - added the new optional `query` request parameter `waId`

[Change history](https://skmtc.dev/indigohive/apis/cogfy-messenger-public-api/changes/contacts/get.md)

---

[API](https://skmtc.dev/indigohive/apis/cogfy-messenger-public-api.md) · [All operations](https://skmtc.dev/indigohive/apis/cogfy-messenger-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/indigohive/cogfy-messenger-public-api/revisions/30bd33ee45c9/schema)