> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/crm/contact/list-contacts.md).

# List contacts

Lists your contacts, newest first, with the inboxes they have talked to you through. Only contacts with at least one conversation in an active inbox are included. Use `POST /api/crm/contact/search` to filter by fields or custom properties.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contacts are the people your business talks to. Each contact has standard fields (name, phone number, email, and so on) plus **custom properties** that you define as columns on your contact board.\n\n## Custom properties\n1. Call `GET /api/crm/contact/filter-fields` or `GET /api/crm/contact/{id}/property` to see the available properties and their column IDs and types.\n2. Read a contact's values from `crm_column` in `GET /api/crm/contact/{contact_id}`. Values are keyed by property name.\n3. Write values with `PUT /api/crm/contact/{id}/property`, or with `values` when creating a contact.\n4. Create new properties with `POST /api/crm/contact/property`.\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"parameters":{"StartDate":{"name":"start_date","in":"query","required":false,"description":"Only include items created on or after this date (`YYYY-MM-DD`). Cannot be combined with `start_datetime`.","schema":{"type":"string","format":"date"}},"EndDate":{"name":"end_date","in":"query","required":false,"description":"Only include items created on or before the end of this date (`YYYY-MM-DD`). Cannot be combined with `end_datetime`.","schema":{"type":"string","format":"date"}},"StartDatetime":{"name":"start_datetime","in":"query","required":false,"description":"Only include items created at or after this time (`YYYY-MM-DDTHH:mm:ss`, optional offset such as `+07:00` or `Z`). Cannot be combined with `start_date`.","schema":{"type":"string"}},"EndDatetime":{"name":"end_datetime","in":"query","required":false,"description":"Only include items created at or before this time (`YYYY-MM-DDTHH:mm:ss`, optional offset). Cannot be combined with `end_date`.","schema":{"type":"string"}},"UserTimezone":{"name":"X-User-Timezone","in":"header","required":false,"description":"IANA time zone used to read date filters that have no offset. Defaults to `Asia/Jakarta`.","schema":{"type":"string"}}},"schemas":{"ContactListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contact_name":{"type":"string"},"email":{"type":"string","nullable":true},"phone_number":{"type":"string","nullable":true},"platform_id":{"type":"string","nullable":true,"description":"The contact's ID on its channel (for example a WhatsApp business-scoped user ID)."},"username":{"type":"string","nullable":true},"platform":{"type":"string","description":"Channel type, for example `whatsapp` or `instagram`."},"created_at":{"type":"string","format":"date-time"},"additional_data":{"type":"object","nullable":true,"additionalProperties":true},"inboxes":{"type":"array","description":"Inboxes the contact has conversations in.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"Pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"total_page":{"type":"integer"},"total_items":{"type":"integer"}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiBadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/contacts":{"get":{"tags":["Contact"],"operationId":"ListContacts","summary":"List contacts","description":"Lists your contacts, newest first, with the inboxes they have talked to you through. Only contacts with at least one conversation in an active inbox are included. Use `POST /api/crm/contact/search` to filter by fields or custom properties.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":10}},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/StartDatetime"},{"$ref":"#/components/parameters/EndDatetime"},{"$ref":"#/components/parameters/UserTimezone"}],"responses":{"200":{"description":"A page of contacts.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactListItem"}},"metadata":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"400":{"$ref":"#/components/responses/ApiBadRequest"},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```