> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List customers
> Returns the list of customers.
**Required scopes:** `customers:ro`
## OpenAPI
````yaml /api/agent-chat/v3.5/openapi.json post /action/list_customers
openapi: 3.0.0
info:
title: Agent Chat API
description: >-
The Agent Chat API allows you to manage chats, threads, events, and agent
state.
version: '3.5'
servers:
- url: https://api.livechatinc.com/v3.5/agent
description: Production server
security: []
paths:
/action/list_customers:
post:
tags:
- Customers
summary: List customers
description: Returns the list of customers.
operationId: list-customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersRequest'
example: {}
responses:
'200':
description: Customers.
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersResponse'
example:
customers:
- id: b7eff798-f8df-4364-8059-649c35c9ed0c
type: customer
name: Thomas Anderson
email: t.anderson@example.com
email_verified: false
avatar: https://example.com/avatars/1.png
present: true
created_at: '2026-06-11T15:19:21.010200Z'
agent_last_event_created_at: '2026-06-12T15:19:21.010200Z'
customer_last_event_created_at: '2026-06-12T15:19:21.010200Z'
statistics:
chats_count: 3
threads_count: 9
visits_count: 5
total_customers: 2340
limited_customers: 120
next_page_id: MTUxNzM5ODEzMTQ5Ng==
previous_page_id: MTUxNzM5ODEzMTQ5Ng==
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- customers:ro
components:
schemas:
ListCustomersRequest:
type: object
properties:
page_id:
type: string
description: Pagination token.
limit:
type: integer
default: 10
maximum: 100
description: Maximum number of records per page.
sort_order:
type: string
enum:
- asc
- desc
default: desc
description: Sort order.
sort_by:
type: string
enum:
- created_at
- threads_count
- visits_count
- agent_last_event
- customer_last_event
default: created_at
description: >-
Sort by field. When sorting by fields other than `created_at`,
entries with identical values are additionally sorted by creation
time.
filters:
type: object
description: Customer filters.
properties:
country:
type: object
additionalProperties: true
description: >-
Filter by country. Accepts `values` or `exclude_values` (string
arrays).
email:
type: object
additionalProperties: true
description: >-
Filter by email. Accepts `values` or `exclude_values` (string
arrays).
name:
type: object
additionalProperties: true
description: >-
Filter by name. Accepts `values` or `exclude_values` (string
arrays).
customer_id:
type: object
additionalProperties: true
description: >-
Filter by customer ID. Accepts `values` or `exclude_values`
(string arrays).
chats_count:
type: object
additionalProperties: true
description: >-
Filter by chats count. Accepts range filter: `lte`, `lt`, `gte`,
`gt`, `eq`.
threads_count:
type: object
additionalProperties: true
description: >-
Filter by threads count. Accepts range filter: `lte`, `lt`,
`gte`, `gt`, `eq`.
visits_count:
type: object
additionalProperties: true
description: >-
Filter by visits count. Accepts range filter: `lte`, `lt`,
`gte`, `gt`, `eq`.
created_at:
type: object
additionalProperties: true
description: >-
Filter by creation date. Accepts date range filter: `lte`, `lt`,
`gte`, `gt`, `eq` (ISO 8601 with microseconds).
agent_last_event_created_at:
type: object
additionalProperties: true
description: Filter by agent last event date. Accepts date range filter.
customer_last_event_created_at:
type: object
additionalProperties: true
description: Filter by customer last event date. Accepts date range filter.
chat_group_ids:
type: object
additionalProperties: true
description: >-
Filter by chat group IDs. Accepts `values` or `exclude_values`
(integer arrays). Maximum 40 group IDs at once.
include_customers_without_chats:
type: boolean
description: Whether to include customers without chats.
ListCustomersResponse:
type: object
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
description: >-
Array of [customer
objects](/api/agent-chat/v3.5/data-structures#customer).
total_customers:
type: integer
description: Total number of customers.
limited_customers:
type: integer
description: Number of customers hidden due to license limits.
next_page_id:
type: string
description: Pagination token for the next page.
previous_page_id:
type: string
description: Pagination token for the previous page.
Customer:
type: object
properties:
id:
type: string
description: The customer ID.
type:
type: string
description: The customer type. Always `customer`.
name:
type: string
description: The customer's name. Returned only if set.
email:
type: string
description: The customer's email. Returned only if set.
avatar:
type: string
description: The customer's avatar. Returned only if set.
phone_number:
type: string
description: The customer's phone number. Returned only if set.
created_at:
type: string
description: The date and time when the customer's identity was created.
session_fields:
type: array
items:
type: object
description: >-
An array of custom object-enclosed key-value pairs. Returned only if
set. Available for the session duration.
statistics:
type: object
description: Counters for started threads, opened pages, etc.
visit:
type: object
description: >-
Geolocation and opened pages from the customer's most recent online
visit. Returned only if the customer logged in at least once.
chat_ids:
type: array
items:
type: string
description: >-
The IDs of the customer's chats. Returned only if the customer had
at least one chat.
omnichannel:
type: object
description: The customer's omnichannel data.
address:
type: object
description: The customer's address data. Returned only if set.
agent_last_event_created_at:
type: string
description: >-
The date and time of the last event created by an agent in this
customer's chats.
customer_last_event_created_at:
type: string
description: The date and time of the last event created by the customer.
securitySchemes:
PersonalAccessToken:
description: >-
Use your `account ID` as the username and your personal access token
(PAT) as the password, or pass a Base64-encoded value directly in the
Authorization header. For more information, see the personal access tokens
guide.
type: http
scheme: basic
OAuth2BearerToken:
description: >-
This API uses OAuth2 with the implicit grant flow. Learn about
the implicit grant flow.
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.livechat.com
scopes:
chats--all:ro: Read all chats
chats--all:rw: Read and write all chats
chats--access:ro: Read chats from groups the agent is a member of
chats--access:rw: Read and write chats from groups the agent is a member of
authorizationCode:
authorizationUrl: https://accounts.livechat.com
tokenUrl: https://accounts.livechat.com/token
scopes:
chats--all:ro: Read all chats
chats--all:rw: Read and write all chats
chats--access:ro: Read chats from groups the agent is a member of
chats--access:rw: Read and write chats from groups the agent is a member of
````