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

# List Chat Contacts

`GET /contacts`

## Request

- Base URL: `https://developers.chatway.app/api/v1`
- URL: `https://developers.chatway.app/api/v1/contacts`
- Auth: API key in header `X-API-KEY`

List visitor contacts and obtain the IDs needed for Get Chat Contact, Update Chat Contact and Create Visitor Message. Each contact's ID is in data[].id. The default page contains up to 10 contacts; the maximum page size is 100.

To keep the response focused, use include_fields with the attributes you need. For example, include_fields=name,email,widget_id selects those contact attributes. The allowed names appear below. If you supply both include_fields and exclude_fields, only include_fields is applied.

## Query parameters

- `search` string, nullable
- `limit` integer, nullable
- `page` integer, nullable
- `include_fields` string, nullable
- `exclude_fields` string, nullable

## Response `200`

Paginated list responses include `data`, `meta.pagination`, and `links`. Use the `page` and `limit` query parameters to walk results. Follow `links.next` until it is `null`, or increment `page` until `current_page >= total_pages`.

| Field | Description |
|---|---|
| `meta.pagination.total` | Total records across all pages |
| `meta.pagination.count` | Records returned on this page |
| `meta.pagination.per_page` | Page size used for this response (matches `limit`) |
| `meta.pagination.current_page` | Current page number (1-based) |
| `meta.pagination.total_pages` | Total number of pages |
| `links.next` | URL for the next page, or `null` on the last page |
| `links.first` / `links.last` | First and last page URLs |

- object
  - `data` object[], required
    - `type` string, required
    - `id` string, required
    - `attributes` object, required: Returned attributes depend on include_fields and exclude_fields. Filtered-out attributes are omitted. The field types below apply when an attribute is present. If both filters are supplied, only include_fields is applied.
      - `widget_name` string, nullable
      - `widget_id` string, nullable
      - `team_id` string, nullable
      - `name` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `country_dialing_code` string, nullable
      - `bgcolor` string, nullable
      - `location` string, nullable
      - `browser_type` string, nullable
      - `country_code` string, nullable
      - `country` string, nullable
      - `country_flag` string, nullable
      - `country_emoji` string, nullable
      - `page_visited` unknown[]
        - unknown
      - `timezone` string, nullable
      - `language` string, nullable
      - `ip` string, nullable
      - `operating_system` string, nullable
      - `online_status` string, nullable
      - `last_active_at` string, nullable
      - `blocked_at` string, nullable
      - `is_name_updated` boolean
      - `created_at` string, nullable
      - `verified_id` string, nullable
      - `verified_email` string, nullable
  - `meta` object, required
    - `pagination` object, required
      - `total` integer, required
      - `count` integer, required
      - `per_page` integer, required
      - `current_page` integer, required
      - `total_pages` integer, required
  - `links` object, required
    - `self` string, required
    - `first` string, required
    - `next` string, nullable, required
    - `last` string, required

## Other responses

- `422`: Validation error

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)