# Customer Search

Customer Search enables merchants to search across a large number of Customers in a Project, supporting back-office use cases.

The Customer Search API is designed to be ID-first—returning only Customer IDs—to provide the best performance. To fetch a Customer, use local caches or the [Get a Customer by ID](/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fcustomers%2F%7Bid%7D%3AGET) endpoint.

In addition to the Merchant Center, the feature also lets you search for Customers in other back-office applications. It is not intended for searching through customers in a storefront.

A maximum of **10000** addresses per Customer can be indexed for Customer Search.

Customer Search is deactivated for a Project, by default. 

To activate, use the [Change Customer Search status](/api/projects/project.md#change-customer-search-status) update action on the Project API or index the Customers in the [Merchant Center](/docs/login.md) (by navigating to **Customers > Customer list**).

If no calls have been made to the [Search Customers](/api/projects/customer-search.md#search-customers) endpoint in the last 30 days, the feature is automatically deactivated for a Project and must be reactivated.

## Representations

#### CustomerSearchRequest

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerSearchRequest).

#### CustomerPagedSearchResponse

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerPagedSearchResponse).

##### CustomerSearchResult

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerSearchResult).

#### CustomerSearchIndexingStatusResponse

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerSearchIndexingStatusResponse).

##### CustomerIndexingProgress

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerIndexingProgress).

##### CustomerIndexingStatus

[type definition](/api/projects/customer-search.md?urn=ctp:api:type:CustomerIndexingStatus).

## Search Customers

To check if an index is available, use the [Check if Customer Search index exists](/api/projects/customer-search.md#check-if-customer-search-index-exists) endpoint. To check the indexing progress and status, use the [Get indexing status of Customer Search](/api/projects/customer-search.md#get-indexing-status-of-customer-search) endpoint.

[endpoint definition](/api/projects/customer-search.md?urn=ctp:api:endpoint:/\{projectKey}/customers/search:POST).

## Get indexing status of Customer Search

[endpoint definition](/api/projects/customer-search.md?urn=ctp:api:endpoint:/\{projectKey}/customers/search/indexing-status:GET).

## Check if Customer Search index exists

[endpoint definition](/api/projects/customer-search.md?urn=ctp:api:endpoint:/\{projectKey}/customers/search:HEAD).

## Searchable Customer fields

The following list contains the [Customer](/urn?urn=ctp%3Aapi%3Atype%3ACustomer) fields that are supported in [simple expressions](/api/search-query-language.md#simple-expressions) for a [CustomerSearchRequest](/api/projects/customer-search.md#customersearchrequest).

### Number and date fields

Use the following fields in [exact](/api/search-query-language.md#exact), [exists](/api/search-query-language.md#exists), and [range](/api/search-query-language.md#range) expressions. **Data type** indicates the [type of field](/api/search-query-language.md#types-of-fields) for the field.

| Standard field | Data type | Query for |
| --- | --- | --- |
| `dateOfBirth` | **date** | [Customers](/api/projects/customers.md#customer) with a certain date of birth. |
| `createdAt` | **dateTime** | Customers created at a certain date and time. |
| `lastModifiedAt` | **dateTime** | Customers last modified at any of its fields at a certain date and time. |
| `version` | **long** | Customers with a certain version of the resource. |

Example:

Find Customers signed up in December 2023:

```json title="Request"
{
  "query": {
    "range": {
      "field": "createdAt",
      "gte": "2023-12-01T00:00:00.000Z",
      "lt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

### Text fields

Use the following text [type fields](/api/search-query-language.md#types-of-fields) in [exact](/api/search-query-language.md#exact), [fullText](/api/search-query-language.md#fulltext), [prefix](/api/search-query-language.md#prefix), [fuzzy](/api/search-query-language.md#fuzzy), [wildcard](/api/search-query-language.md#wildcard), and [exists](/api/search-query-language.md#exists) query expressions.

| Standard field | Query for |
| --- | --- |
| `addresses.all` | [Customers](/api/projects/customers.md#customer) with a certain string in the combination of all [Address](/api/types.md#baseaddress) fields. |
| `addresses.city` | Customers with a certain string in the `city` field of all the Customer's addresses. |
| `addresses.company` | Customers with a certain string in the `company` field of all the Customer's addresses. |
| `addresses.country` | Customers with a certain string in the `country` field of all the Customer's addresses. |
| `addresses.firstName` | Customers with a certain string in the `firstName` field of all the Customer's addresses. |
| `addresses.lastName` | Customers with a certain string in the `lastName` field of all the Customer's addresses. |
| `addresses.mobile` | Customers with a certain string in the `mobile` field of all the Customer's addresses. |
| `addresses.phone` | Customers with a certain string in the `phone` field of all the Customer's addresses. |
| `addresses.postalCode` | Customers with a certain string in the `postalCode` field of all the Customer's addresses. |
| `addresses.streetName` | Customers with a certain string in the `streetName` field of all the Customer's addresses. |
| `addresses.streetNumber` | Customers with a certain string in the `streetNumber` field of all the Customer's addresses. |
| `all` | Customers with a certain string in any of the Customer's fields.  Does not support [wildcard expressions](/api/search-query-language.md#wildcard). |
| `companyName` | Customers working for a certain company. |
| `email` | Customers with a certain email address. |
| `firstName` | Customers with a certain first name. |
| `lastName` | Customers with a certain last name. |
| `middleName` | Customers with a certain middle name. |
| `fullName` | Customers with a certain string in their full name as a combination of `firstName`, `middleName`, and `lastName` fields. |

Examples:

Find Customers with the first name of John (case insensitive):

```json title="Request"
{
  "query": {
    "fullText": {
      "field": "firstName",
      "value": "john"
    }
  }
}
```

Find Customers mentioning "example" in any field. This query will not only find "example" in fields like `companyName`, but also in `email` addresses like [email@example.com](mailto:email@example.com).

```json title="Request"
{
  "query": {
    "fullText": {
      "field": "all",
      "value": "example"
    }
  }
}
```

### Keyword fields

Use the following keyword [type fields](/api/search-query-language.md#types-of-fields), containing unique IDs or keys, in [exact](/api/search-query-language.md#exact), [prefix](/api/search-query-language.md#prefix), [wildcard](/api/search-query-language.md#wildcard), and [exists](/api/search-query-language.md#exists) expressions.
To query for multiple values of the same field or for several fields in the same request, combine the simple expressions with a [compound expression](/api/search-query-language.md#compound-expressions).

| Standard field | Query for |
| --- | --- |
| `id` | a [Customer](/urn?urn=ctp%3Aapi%3Atype%3ACustomer) with a specific `id`. |
| `key` | a Customer with a specific `key`. |
| `customerNumber` | a Customer with a specific `customerNumber`. |
| `externalId` | a Customer with a specific `externalId`. |
| `vatId` | a Customer with a specific `vatId`. |
| `customerGroupAssignments.customerGroup.id` | a Customer in a specific [CustomerGroup](/urn?urn=ctp%3Aapi%3Atype%3ACustomerGroup) identified by its `id`. |
| `customerGroup.id` | Customers with a specific [CustomerGroup](/urn?urn=ctp%3Aapi%3Atype%3ACustomerGroup) identified by its `id`. |
| `stores.key` | Customers of a specific [Store](/urn?urn=ctp%3Aapi%3Atype%3AStore) identified by its `key`. |

Example:

Find Customers associated with one of the specified Stores:

```json title="Request"
{
  "query": {
    "or": [
      {
        "exact": {
          "field": "stores.key",
          "value": "store1"
        }
      },
      {
        "exact": {
          "field": "stores.key",
          "value": "store2"
        }
      },
      {
        "exact": {
          "field": "stores.key",
          "value": "store3"
        }
      }
    ]
  }
}
```

### Custom Fields

In addition to the standard fields on a Customer, you can also search for its [Custom Fields](/api/projects/custom-fields.md), if any. `custom.<field-name>` queries for Customers with a Custom Field of a specific name, and the [SearchFieldType](/api/search-query-language.md#searchfieldtype) determines the data type of the field.

The `ltext` [SearchFieldType](/api/search-query-language.md#searchfieldtype) is not supported.

To query `enum` and `lenum` [SearchFieldTypes](/api/search-query-language.md#searchfieldtype), use the `key` of the enum value.

Example: An exact query to find Customers with an [enum type](/api/projects/types.md#customfieldenumtype) Custom Field `accountPlan` to the enum key of `silver`.

```json title="Request"
{
  "query": {
    "exact": {
      "field": "custom.accountPlan.key",
      "value": "silver",
      "fieldType": "enum"
    }
  }
}
```

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Customers](/api/projects/customers.md)
- [Next page: Customer Groups](/api/projects/customerGroups.md)