> ## 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
> Available for Text App only. Searches and lists customers with filtering, sorting, and pagination.
**Required scopes:** `customers:ro`
## OpenAPI
````yaml /api/customer-data-platform/openapi.json post /v1/list_customers
openapi: 3.0.0
info:
title: Customer Data Platform API
description: A service for collecting, storing, and managing end-user data.
version: 0.0.1
servers:
- url: https://api.text.com/cdp
description: Main production server URL
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- customers:ro
paths:
/v1/list_customers:
post:
tags:
- Customers
summary: List customers
description: >-
Available for Text App only. Searches and lists customers with
filtering, sorting, and pagination.
operationId: list-customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersRequest'
examples:
simple_search:
summary: Simple free-text search
value:
query: john
results_per_page: 50
advanced_filters:
summary: Advanced filtering with multiple criteria
value:
query: john
filters:
- operator: AND
clauses:
- field: name
operator: contains
values:
- john
- jane
- field: country
operator: is
values:
- Poland
- Latvia
negate: true
- field: last_activity
operator: range
range:
from: '2026-06-01T00:00:00Z'
to: '2026-06-01T00:00:00Z'
- field: threads_count
operator: range
range:
from: 50
to: 100
- field: tickets_count
operator: is
values:
- 10
results_per_page: 50
sort:
last_activity: desc
filter_groups_example:
summary: Multiple filter groups with OR logic
value:
filters:
- operator: AND
clauses:
- field: email
operator: is
values:
- user@example.com
- field: threads_count
operator: range
range:
from: 10
to: 100
- operator: OR
clauses:
- field: name
operator: exists
- field: phone_number
operator: starts_with
values:
- '+48'
- '+121'
results_per_page: 25
cart_filters:
summary: Filter by cart value and last updated date
value:
filters:
- operator: AND
clauses:
- field: cart_total_usd
operator: range
range:
from: 100
to: 500
- field: cart_last_updated_at
operator: range
range:
from: '2026-06-01T00:00:00Z'
to: '2026-06-01T00:00:00Z'
results_per_page: 50
responses:
'200':
description: A list of customers matching the search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersResponse'
example:
customers:
- customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
organization_id: b7eff798-f8df-4364-8052-649c35c9ed0c
product: livechat
monitoring: null
custom_fields: null
statistics: null
next_page_id: '2'
total: 1523
page_id: '1'
'400':
description: Invalid request (validation error).
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: >-
validation error: invalid field 'city'. Allowed fields:
name, email, phone_number, country, and statistics fields
example:
error: >-
validation error: invalid field 'city'. Allowed fields: name,
email, phone_number, country, and statistics fields
'401':
description: Invalid access token
'403':
description: Insufficient scopes
'422':
description: Invalid request body
'500':
description: Internal error
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- customers:ro
components:
schemas:
ListCustomersRequest:
allOf:
- $ref: '#/components/schemas/CustomerSearchBase'
- type: object
properties:
results_per_page:
type: integer
minimum: 1
maximum: 100
default: 50
description: The number of results to return per page.
sort:
type: object
description: >-
The sorting configuration (field -> order mapping). Multiple
sort fields can be specified. Note: `created_at` is always
appended as the final sort field to ensure stable pagination.
additionalProperties:
type: string
enum:
- asc
- desc
example:
last_activity: desc
name: asc
page_id:
type: string
description: >-
The page identifier for pagination. Should be a numeric string
starting from `"1"`. Use the `next_page_id` from the previous
response to navigate to the next page.
example: '1'
example:
query: john
filters:
- operator: AND
clauses:
- field: name
operator: contains
values:
- john
- jane
- field: email
operator: is
values:
- user@example.com
- contact@example.com
- field: country_code
operator: is
values:
- US
negate: true
- field: last_activity
operator: range
range:
from: '2026-06-01T00:00:00Z'
to: '2026-06-01T00:00:00Z'
- field: threads_count
operator: range
range:
from: 50
to: 100
- field: cart_total_usd
operator: range
range:
from: 50
to: 200
- field: cart_last_updated_at
operator: range
range:
from: '2026-06-01T00:00:00Z'
to: '2026-06-01T00:00:00Z'
- operator: OR
clauses:
- field: name
operator: exists
- field: email
operator: exists
results_per_page: 50
sort:
last_activity: desc
name: asc
page_id: '1'
ListCustomersResponse:
type: object
required:
- customers
- total
- page_id
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
description: An array of customer objects matching the search criteria.
next_page_id:
type: string
description: >-
The page identifier for the next page of results. Empty string if
there are no more pages. Pass this value as `page_id` in the next
request to retrieve the next page.
example: '2'
total:
type: integer
format: int32
description: The total number of customers matching the search criteria.
example: 1523
page_id:
type: string
description: The current page identifier.
example: '1'
CustomerSearchBase:
type: object
properties:
query:
type: string
minLength: 3
description: >-
A free-text search query across `name`, `email`, and `phone_number`
fields. Automatically excludes fields that are explicitly filtered.
example: john smith
filters:
type: array
description: An array of filter groups combined with `AND` logic.
items:
$ref: '#/components/schemas/FilterGroup'
Customer:
type: object
required:
- customer_id
- organization_id
- product
- monitoring
- custom_fields
- statistics
properties:
customer_id:
type: string
format: uuid
organization_id:
type: string
format: uuid
product:
type: string
example: livechat
monitoring:
allOf:
- $ref: '#/components/schemas/Monitoring'
nullable: true
custom_fields:
allOf:
- $ref: '#/components/schemas/CustomFields'
nullable: true
statistics:
allOf:
- $ref: '#/components/schemas/Statistics'
nullable: true
chat:
$ref: '#/components/schemas/Chat'
invitation:
$ref: '#/components/schemas/Invitation'
tickets:
type: object
additionalProperties:
$ref: '#/components/schemas/Ticket'
omnichannel:
$ref: '#/components/schemas/Omnichannel'
orders:
type: array
items:
$ref: '#/components/schemas/Order'
carts:
type: array
items:
$ref: '#/components/schemas/Cart'
FilterGroup:
type: object
required:
- operator
- clauses
properties:
operator:
type: string
enum:
- AND
- OR
description: The logical operator to combine clauses within this group.
clauses:
type: array
minItems: 1
description: The filter clauses to be combined with the specified operator.
items:
$ref: '#/components/schemas/Clause'
example:
operator: AND
clauses:
- field: name
operator: contains
values:
- john
- field: email
operator: exists
Monitoring:
type: object
required:
- name
- name_is_default
- email
- avatar_url
- phone_number
- session_fields
- visits
- version
- state
- online
- current_group_ids
- created_at
- master_id
properties:
name:
type: string
name_is_default:
type: boolean
email:
type: string
avatar_url:
type: string
phone_number:
type: string
session_fields:
type: array
items:
type: object
properties:
key:
type: string
value:
type: string
visits:
type: array
items:
$ref: '#/components/schemas/Visit'
version:
type: integer
state:
$ref: '#/components/schemas/MonitoringState'
online:
type: boolean
current_group_ids:
type: array
items:
type: integer
created_at:
type: string
format: date-time
master_id:
type: string
format: uuid
address:
$ref: '#/components/schemas/Address'
CustomFields:
type: object
additionalProperties:
type: object
additionalProperties:
type: string
example:
58737b5829e65621a45d598aa6f2ed8e:
phone: 0300 222 0000
address: Prime Minister's Office, 10 Downing Street
Statistics:
type: object
required:
- chats_count
- threads_count
- visits_count
- page_views_count
- greetings_accepted_count
- greetings_converted_count
- tickets_count
- tickets_inbox_count
- tickets_archive_count
- tickets_spam_count
- tickets_trash_count
- orders_count
properties:
chats_count:
type: integer
threads_count:
type: integer
visits_count:
type: integer
page_views_count:
type: integer
greetings_accepted_count:
type: integer
greetings_converted_count:
type: integer
tickets_count:
type: integer
tickets_inbox_count:
type: integer
tickets_archive_count:
type: integer
tickets_spam_count:
type: integer
tickets_trash_count:
type: integer
orders_count:
type: integer
last_activity_at:
type: string
format: date-time
last_visit_at:
type: string
format: date-time
last_ticket_created_at:
type: string
format: date-time
last_ticket_customer_message_at:
type: string
format: date-time
last_chat_at:
type: string
format: date-time
last_omnichannel_chat_at:
type: string
format: date-time
last_campaign_interaction_at:
type: string
format: date-time
Chat:
type: object
required:
- active
- chat_id
- thread_id
- last_updated_at
- group_ids
properties:
active:
type: boolean
chat_id:
type: string
thread_id:
format: string
last_updated_at:
type: string
format: date-time
group_ids:
type: array
items:
type: integer
source_customer_client_id:
type: string
Invitation:
type: object
required:
- active
- greeting_id
- greeting_unique_id
- greeting_name
properties:
active:
type: boolean
greeting_id:
type: integer
greeting_unique_id:
format: uuid
greeting_name:
type: string
Ticket:
type: object
required:
- ticket_id
- hd_license_id
- status
- created_at
- last_updated_at
properties:
ticket_id:
type: string
format: uuid
hd_license_id:
type: string
status:
type: string
silo:
$ref: '#/components/schemas/TicketSilo'
created_at:
type: string
format: date-time
last_updated_at:
type: string
format: date-time
last_customer_message_at:
type: string
format: date-time
Omnichannel:
type: object
properties:
fbmessenger:
type: array
items:
$ref: '#/components/schemas/OmnichannelFBMessenger'
twilio:
type: array
items:
$ref: '#/components/schemas/OmnichannelTwilio'
whatsapp:
type: array
items:
$ref: '#/components/schemas/OmnichannelWhatsApp'
Order:
type: object
required:
- customer_id
- store_platform
- store_uuid
- order_id
- order_number
- currency
- total_price
- created_at
- event_id
- event_client_id
properties:
customer_id:
type: string
format: uuid
store_platform:
type: string
store_uuid:
type: string
format: uuid
order_id:
type: string
order_number:
type: string
currency:
type: string
total_price:
type: number
format: double
created_at:
type: string
format: date-time
event_id:
type: string
format: uuid
event_client_id:
type: string
line_items:
type: array
items:
$ref: '#/components/schemas/OrderLineItem'
Cart:
type: object
required:
- store_uuid
- store_platform
- customer_signed_in
- subtotal
- total
- subtotal_usd
- total_usd
- currency
- items
- last_updated_at
properties:
store_uuid:
type: string
format: uuid
store_platform:
type: string
customer_signed_in:
type: boolean
subtotal:
type: number
format: double
total:
type: number
format: double
subtotal_usd:
type: number
format: double
total_usd:
type: number
format: double
currency:
type: string
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
last_updated_at:
type: string
format: date-time
Clause:
type: object
required:
- operator
properties:
field:
type: string
enum:
- name
- email
- phone_number
- phone_number_country_code
- country
- country_code
- last_activity
- last_visit_started
- visits_count
- page_views_count
- chats_count
- threads_count
- greetings_accepted_count
- greetings_converted_count
- tickets_count
- tickets_inbox_count
- tickets_archive_count
- tickets_spam_count
- tickets_trash_count
- orders_count
- cart_last_updated_at
- cart_total_usd
- address_street
- address_city
- address_country
- address_state
- address_postal_code
description: The field name to filter on (required for all operators).
operator:
type: string
enum:
- contains
- is
- range
- exists
- starts_with
description: >-
The filter operator:
- `exists` — Check if field exists/is populated (name, email,
phone_number, address_street, address_city, address_country,
address_state, address_postal_code)
- `contains` — Partial string matching (name, email, phone_number,
address_street, address_city, address_country, address_state,
address_postal_code)
- `is` — Exact match for single or multiple values (all fields)
- `range` — Range filter for dates, numbers, or cart values
(statistics fields, cart fields)
- `starts_with` — Prefix match (phone_number, address_postal_code).
values:
type: array
maxItems: 200
items:
type: string
description: >-
An array of values for operators: `contains`, `is`, `starts_with`.
Multiple values are combined with OR logic. For the `starts_with`
operator: minimum 3 characters per value.
example:
- john
- jane
range:
type: object
properties:
from:
oneOf:
- type: string
format: date-time
- type: integer
- type: number
format: double
description: >-
The start of the range (inclusive, gte). For date fields
(last_activity, last_visit_started, cart_last_updated_at): use
RFC3339 date-time strings (e.g., `2026-06-01T00:00:00Z`). For
numeric fields (visits_count, threads_count, etc.): use
integers. For cart value fields (cart_total_usd): use numbers
(e.g., 50.00).
to:
oneOf:
- type: string
format: date-time
- type: integer
- type: number
format: double
description: >-
The end of the range (inclusive, lte). For date fields
(last_activity, last_visit_started, cart_last_updated_at): use
RFC3339 date-time strings (e.g., `2026-06-01T00:00:00Z`). For
numeric fields (visits_count, threads_count, etc.): use
integers. For cart value fields (cart_total_usd): use numbers
(e.g., 200.00).
description: >-
The range values for the `range` operator. For date fields
(last_activity, last_visit_started, cart_last_updated_at): use
RFC3339 format date-time strings. For numeric fields (visits_count,
threads_count, etc.): use integers. For cart value fields
(cart_total_usd): use numbers.
example:
from: '2026-06-01T00:00:00Z'
to: '2026-06-01T00:00:00Z'
negate:
type: boolean
default: false
description: >-
If set to `true`: the filter result is negated (NOT logic is
applied).
example:
field: name
operator: contains
values:
- john
- jane
Visit:
type: object
required:
- id
- started_at
- geolocation
properties:
id:
type: integer
started_at:
type: string
ended_at:
type: string
geolocation:
$ref: '#/components/schemas/Geolocation'
ip:
type: string
user_agent:
type: string
page_referrer:
type: string
first_visited_page:
$ref: '#/components/schemas/Page'
pages:
type: array
items:
$ref: '#/components/schemas/Page'
MonitoringState:
type: string
enum:
- ''
- browsing
- queued
- invited
- chatting
- chat closed
- offline
Address:
type: object
properties:
address:
type: string
city:
type: string
country:
type: string
state:
type: string
postal_code:
type: string
TicketSilo:
type: string
enum:
- inbox
- archive
- spam
- trash
OmnichannelFBMessenger:
type: object
required:
- id
- is_verified_user
properties:
id:
type: string
format: uuid
name:
type: string
first_name:
type: string
last_name:
type: string
profile_pic:
type: string
format: url
gender:
type: string
locale:
type: string
is_verified_user:
type: boolean
OmnichannelTwilio:
type: object
required:
- phone_number
properties:
phone_number:
type: string
OmnichannelWhatsApp:
type: object
required:
- id
- phone_number
properties:
id:
type: string
name:
type: string
phone_number:
type: string
OrderLineItem:
type: object
required:
- title
- quantity
- price
properties:
title:
type: string
quantity:
type: integer
price:
type: number
format: double
sku:
type: string
variant_id:
type: string
product_id:
type: string
CartItem:
type: object
required:
- id
- quantity
- variant_id
properties:
id:
type: integer
format: int64
quantity:
type: integer
variant_id:
type: integer
format: int64
discounts:
type: array
items:
type: string
Geolocation:
type: object
required:
- latitude
- longitude
- country
- country_code
- region
- city
- timezone
properties:
latitude:
type: string
longitude:
type: string
country:
type: string
country_code:
type: string
region:
type: string
city:
type: string
timezone:
type: string
Page:
type: object
required:
- id
- started_at
- url
- title
- group_ids
properties:
id:
type: integer
started_at:
type: string
url:
type: string
title:
type: string
group_ids:
type: array
items:
type: integer
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: {}
authorizationCode:
authorizationUrl: https://accounts.livechat.com
tokenUrl: https://accounts.livechat.com/token
scopes: {}
````