---
title: "Get all customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# Get all customers

`GET /customers`

Get a list of all customers.

Customers are the central entity of the CareCloud CRM. Each account stores personal and contact details, loyalty program participation (cards, points, credits, vouchers), communication preferences and consent status, segments, custom properties, related customers, addresses, interests, and partner and source assignments.

Supports filtering by email, phone, first name, last name, date of birth, customer source, and a list of customer IDs. Use `email_list` to retrieve multiple customers by email in a single request.

Related: [POST /customers](https://carecloud.readme.io/reference/postcustomer), [GET /customers/{customer_id}](https://carecloud.readme.io/reference/getcustomer), [GET /customers/actions/search-customers](https://carecloud.readme.io/reference/getcustomersearch) (enterprise interface only)

## Query parameters

- `count` integer
- `offset` integer
- `sort_field` string
- `sort_direction` 'ASC' | 'DESC'
- `email` string
- `phone` string
- `customer_source_id` string
- `first_name` string
- `last_name` string
- `birthdate` string
- `email_list` string[]
- `customer_ids` string[]
- `customer_short_salutation` boolean

## Headers

- `Accept-Language` string

## Response `200`

OK

- object
  - `data` object
    - `customers` Customer[] — Array of customers.
      - `customer_id` string — The unique ID of the customer.
      - `personal_information` PersonalInformation, required — Personal information of the customer.
        - `salutation` string — Customer's salutation. If it is not set in POST or PUT calls, it will be generated automatically.
        - `gender` 1 | 2 | 3 | 4 | 5, nullable — Gender of the customer *Possible values: 1 - Male / 2 - Female / 3 - Miss / 4 - Private / 5 - Other *
        - `first_name` string — First name of the customer.
        - `last_name` string — Last name of the customer.
        - `pre_nominals` string — Academic degrees, academic titles, other titles of customer placed before name.
        - `post_nominals` string — Academic degrees, academic titles, other titles of customer placed after name.
        - `birthdate` string, date — Customer's date of birth in ISO-8601 format (`YYYY-MM-DD`).
        - `email` string — Email of the customer. If you provide an email address, CareCloud validates its format and the validity of the domain. Here is the general regular expression that is used for validation: `^[-a-z0-9!#$%&'*+\\/=?^_`{|}~]+(\\.[-a-z0-9!#$%&'*+\\/=?^_`{|}~]+)*@([a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?\\.)+[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])$`
        - `phone` string — Phone number of the customer with international prefix (420000000000).
        - `language_id` string, required — The unique ID of the language by ISO 639-1 code. [GET /languages](https://carecloud.readme.io/reference/getlanguages)
        - `store_id` string — The unique ID of the original customer account store of registration. In case of customer update, the value can only be updated, not removed. When provided during customer registration and the project is configured for store-based partner assignment, the system derives the partner from the store and creates a single customer-partner relation. [GET /stores](https://carecloud.readme.io/reference/getstores)
        - `photo_url` string — URL address of the customer photo. If customer has no photo, this parameter is not send.
        - `address` Address — The Address Structure in the API defines the standardized format for representing addresses throughout the system. This resource ensures consistency and accuracy in capturing address details, facilitating seamless integration and data exchange.
          - `address1` string — Street name of the address.
          - `address2` string — Street number (Land registry number).
          - `address3` string — House number.
          - `address4` string — Next address data.
          - `address5` string — Next address data.
          - `address6` string — Next address data.
          - `address7` string — Next address data.
          - `zip` string — ZIP code.
          - `city` string — City.
          - `country_code` string — ISO code of the country. *Possible values de / gb / us / it / cz / etc*
        - `agreement` Agreement — Customer's consents.
          - `agreement_gtc` 0 | 1 | 2 — Consent to the Personal data processing. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set*
          - `agreement_profiling` 0 | 1 | 2 — Consent to the Profiling. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set*
          - `agreement_marketing_communication` 0 | 1 | 2 — Consent to the Marketing communication. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set*
          - `custom_agreements` CustomAgreements[] — Custom consent list. The list of consents is available in the [Consents resource](https://carecloud.readme.io/reference/getconsents)
            - `agreement_id` string, required — The unique ID of the consent in CareCloud from [consents](https://carecloud.readme.io/reference/getconsents) resource.
            - `agreement_value` 0 | 1 | 2, required — Value of the specific consent. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set*
        - `consents` Consents[] — The list of all customer consents. The list of consents is available in the [Consents resource](https://carecloud.readme.io/reference/getconsents). This parameter replaces the deprecated `agreement` parameter. If both parameters are provided, `consents` takes effect and `agreement` is ignored entirely.
          - `consent_id` string, required — The unique ID of the consent in CareCloud from [consents](https://carecloud.readme.io/reference/getconsents) resource.
          - `consent_value` 0 | 1 | 2, required — Value of the specific consent. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set*
          - `last_change` string — Timestamp of the last change of the record. Format: `YYYY-MM-DD HH:MM:SS`. All times are in the local timezone.
      - `doi_email` string — Date and time of obtaining the customer's email consent (Double opt-in confirmation). *(YYYY-MM-DD HH:MM:SS)*
      - `doi_phone` string — Date and time of obtaining the customer's phone consent (Double opt-in confirmation). *(YYYY-MM-DD HH:MM:SS)*
      - `last_change` string — Date and time of the last change. *(YYYY-MM-DD HH:MM:SS)*
      - `state` 0 | 1 | 2 — State of the customer. *Possible values are: 0 - deleted / 1 - active / 2 - non active*
    - `total_items` integer — The number of all found customers.

## Other responses

- `400` — Bad input parameter. The response body's `error.error_data.invalid_params[]` array lists the parameters that caused the failure, each carrying a `reason` code. See the `BadRequestErrorBody` schema for the generic reason taxonomy. Operations with domain-specific business rules document additional reasons at the operation level.
- `401` — The client has invalid credentials or auth token.
- `403` — The client does not exist or the client tried to access an unauthorized property or resource.
- `404` — The resource was not found.
- `405` — The resource does not support the specified HTTP method.
- `429` — Too many requests - more than the resource limit.
- `500` — Server is not working as expected.
- `503` — Temporary state when the service is temporarily unavailable, overloaded or there is a maintenance window.

---

[API](https://skmtc.net/crmcarecloud/apis/rest-api-reference.md) · [All operations](https://skmtc.net/crmcarecloud/apis/rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crmcarecloud/rest-api-reference/revisions/329c06dbf8d9/schema)