--- schema_version: "1" id: d3d2b1265a8e21008ee3802982d56d7d25d44094328d0ef7c3005a484f400c54 title: Data Customer Lists (deprecated) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-customer-lists.md canonical_url: https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-customer-lists source_site: developer.salesforce.com content_type: documentation content_hash: 2315d36bd82b0f4f179a1c248954c49a2f83f46143c590628f1e695149662fc9 products: - B2C Commerce - Salesforce APIs --- Data Customer Lists (deprecated) # Data Customer Lists (deprecated) Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage. **Version:** 25.6 ## Servers * `https://{host}/s/-/dw/data/v25_6` Protocols: https. ## Security * `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager. * OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token) * Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required. * `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter. * API key in header: x-dw-client-id ## Operations ### POST Search for customers in a customer list `POST /customer_lists/{customer_list_id}/customer_search` Operation ID: `Search for customers in a customer list`. Tags: customer\_lists. Security: oauth2\_application. Action to search for customers in a customer list. The query attribute specifies a complex query that can be used to narrow down the search. Note that a text\_query search only returns exact word matches. For example, the search term "Jon" returns "Jon Smith", but doesn't return "Jonathan Smith". The sum of the values of the start and count parameters should not be more than 10000. These attributes are searchable: * customer\_no - String * first\_name - String * second\_name - String * last\_name - String * suffix - String * salutation - String * title - String * fax - String * phone\_home - String * phone\_business - String * phone\_mobile - String * email - String * gender - Integer * company\_name - String * credentials.login - String * credentials.enabled - boolean #### Parameters * `customer_list_id` (path, string, required) The customer list id to search in Minimum length: 1. Maximum length: 256. #### Request body (required) Media type: `application/json, text/xml`. Schema: `search_request`. #### Responses * **default** Media type: `application/json, text/xml`. Schema: `customer_search_result`. ### GET Get customer list `GET /customer_lists/{list_id}` Operation ID: `Get customer list`. Tags: customer\_lists. Security: oauth2\_application. Action to read an existing customerlist. This endpoint may return the following faults: * 404 - CustomerListNotFoundException - Indicates that there was no customerlist found for the customerlist id. #### Parameters * `list_id` (path, string, required) the id of the customerlist Minimum length: 1. #### Responses * **404** `CustomerListNotFoundException` - Indicates that there was no customerlist found for the customerlist id. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer_list`. ### POST Create customer `POST /customer_lists/{list_id}/customers` Operation ID: `Create customer`. Tags: customer\_lists. Security: oauth2\_application. Action to create a new customer. The customer is created using the specified credentials and customer information.This action verifies the following: * Login acceptance criteria and uniqueness * Mandatory customer properties If the action fails to create the customer, it returns a 400 fault with an appropriate message. This endpoint may return the following faults: * 400 - CredentialsMissingException - Indicates that the mandatory credentials are missing in the input document. * 400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria. * 400 - LoginAlreadyInUseException - Indicates the login is already in use. * 400 - LoginMissingException - Indicates that the mandatory login property is missing in the input document. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `customer`. #### Responses * **400** `CredentialsMissingException` - Indicates that the mandatory credentials are missing in the input document. or `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates the login is already in use. or `LoginMissingException` - Indicates that the mandatory login property is missing in the input document. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer`. ### GET Get customer `GET /customer_lists/{list_id}/customers/{customer_no}` Operation ID: `Get customer`. Tags: customer\_lists. Security: oauth2\_application. Action to get customer information. This endpoint may return the following faults: * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. #### Responses * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer`. ### PUT Create customer with given customer number `PUT /customer_lists/{list_id}/customers/{customer_no}` Operation ID: `Create customer with given customer number`. Tags: customer\_lists. Security: oauth2\_application. Action to create a new customer. The customer is created using the specified customer number, credentials and customer information.This action verifies the following: * Login acceptance criteria and uniqueness * Mandatory customer properties If the action fails to create the customer, it returns a 400 fault with an appropriate message. This endpoint may return the following faults: * 400 - CredentialsMissingException - Indicates that the mandatory credentials are missing in the input document. * 400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria. * 400 - LoginAlreadyInUseException - Indicates that the given login is already in use. * 400 - LoginMissingException - Indicates that the mandatory login property is missing in the input document. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `customer`. #### Responses * **400** `CredentialsMissingException` - Indicates that the mandatory credentials are missing in the input document. or `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates that the given login is already in use. or `LoginMissingException` - Indicates that the mandatory login property is missing in the input document. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer`. ### DELETE Delete customer `DELETE /customer_lists/{list_id}/customers/{customer_no}` Operation ID: `Delete customer`. Tags: customer\_lists. Security: oauth2\_application. Deletes the customer including all related information like the customer addresses. Returns a status code of 204 on successful completion when deleting the customer. If the customer to be deleted did not exist, a 204 will still be returned to indicate the resource is no longer present in the system. This endpoint may return the following faults: * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. #### Responses * **204** * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. ### PATCH Update customer `PATCH /customer_lists/{list_id}/customers/{customer_no}` Operation ID: `Update customer`. Tags: customer\_lists. Security: oauth2\_application. Updates the customer with the specified information. The customer number is allowed to be updated but will result in a CustomerNumberAlreadyInUseException if there is already another customer with the same customer number existing. This endpoint may return the following faults: * 400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria. * 400 - LoginAlreadyInUseException - Indicates the login is already in use. * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `customer`. #### Responses * **400** `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates the login is already in use. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer`. ### GET Get all customer addresses `GET /customer_lists/{list_id}/customers/{customer_no}/addresses` Operation ID: `Get all customer addresses`. Tags: customer\_lists. Security: oauth2\_application. Action that returns a pageable list of all customer addresses. The default page size is 10 customer addresses. This endpoint may return the following faults: * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. * `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0. Minimum: 0. * `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25. Minimum: 1. Maximum: 200. #### Responses * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer_address_result`. ### POST Create customer address `POST /customer_lists/{list_id}/customers/{customer_no}/addresses` Operation ID: `Create customer address`. Tags: customer\_lists. Security: oauth2\_application. The action creates a new customer address with the given address information. This endpoint may return the following faults: * 400 - AddressIdAlreadyInUseException - If the address id is already in use. * 400 - InvalidAddressIdException - If the address id is null or empty. * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `customer_address`. #### Responses * **400** `AddressIdAlreadyInUseException` - If the address id is already in use. or `InvalidAddressIdException` - If the address id is null or empty. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer_address`. ### GET Get customer address `GET /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}` Operation ID: `Get customer address`. Tags: customer\_lists. Security: oauth2\_application. Action which returns an address of a customer. This endpoint may return the following faults: * 404 - CustomerListCustomerAddressNotFoundException - Indicates that the customer address id is unknown. * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. * `address_id` (path, string, required) The address id Minimum length: 1. #### Responses * **404** `CustomerListCustomerAddressNotFoundException` - Indicates that the customer address id is unknown. or `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer_address`. ### DELETE Delete customer address `DELETE /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}` Operation ID: `Delete customer address`. Tags: customer\_lists. Security: oauth2\_application. Action which deletes a customer address. This endpoint may return the following faults: * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. * `address_id` (path, string, required) The address id Minimum length: 1. #### Responses * **204** * **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. ### PATCH Update customer address `PATCH /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}` Operation ID: `Update customer address`. Tags: customer\_lists. Security: oauth2\_application. Action which updates an address of a customer with the given address information. This endpoint may return the following faults: * 400 - AddressIdAlreadyInUseException - If the new address id is already in use. * 400 - InvalidAddressIdException - If the new address id is empty. * 404 - CustomerListCustomerAddressNotFoundException - Indicates that the customer address id is unknown. * 404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown. * 404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown. #### Parameters * `list_id` (path, string, required) The customer list id Minimum length: 1. * `customer_no` (path, string, required) The customer number Minimum length: 1. * `address_id` (path, string, required) The address id Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `customer_address`. #### Responses * **400** `AddressIdAlreadyInUseException` - If the new address id is already in use. or `InvalidAddressIdException` - If the new address id is empty. Media type: `application/json, text/xml`. Schema: `fault`. * **404** `CustomerListCustomerAddressNotFoundException` - Indicates that the customer address id is unknown. or `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown. Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `customer_address`. ## Schemas ### search\_request Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource. * `count` (_integer (int32)_) The number of returned documents Minimum: 1. Maximum: 200. * `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling Minimum: 0. * `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional * `query` (_query_, required) The query to apply * `select` (_string_) The field to be selected. * `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. ### customer\_search\_result Document representing a customer search result. * `count` (_integer (int32)_) The number of returned documents * `data` (_array of object_) * `db_start_record_` (_integer (int32)_) Minimum: 0. * `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional * `hits` (_array of customer\_search\_hit_) The sorted array of search hits. Can be empty. * `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page. * `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page. * `query` (_query_) The query passed into the search * `select` (_string_) The field to be selected. * `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. * `total` (_integer (int32)_) The total number of documents. _Example_ ``` { "count": 1, "hits": [ { "data": { "customer_no": "000007" }, "relevance": 1.5439257621765137 } ], "query": { "text_query": { "fields": [ "credentials.login" ], "search_phrase": "mmiller" } }, "start": 0, "total": 1 } ``` ### fault Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error). * `arguments` (_object_) A map that provides fault arguments. Data can be used to provide error messages on the client side. Additional properties: `object`. * `cause` (_cause_) * `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given * `message` (_string_) The message text of the java exception. * `stack_trace` (_string_) * `type` (_string_) The name of the java exception. ### customer\_list Document representing a customer list. * `id` (_string_, required) The id of the customer list. Minimum length: 1. * `preferences` (_customer\_list\_preferences_) The preferences of the customer list. _Example_ ``` { "id": "SiteGenesis" } ``` ### customer Document representing a customer. * `birthday` (_string (date)_) The customer's birthday. * `company_name` (_string_) The customer's company name. Maximum length: 256. * `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'. * `credentials` (_credentials_) The customer's credentials. * `customer_id` (_string_) The customer's id. Both registered and guest customers have a customer id. Maximum length: 28. * `customer_no` (_string_) The customer's number. Maximum length: 100. * `email` (_string (email)_) The customer's email address. Maximum length: 256. * `fax` (_string_) The fax number to use for the customer. The length is restricted to 32 characters. Maximum length: 32. * `first_name` (_string_) The customer's first name. Maximum length: 256. * `gender` (_integer (int32)_) The customer's gender. Allowed values: `1`, `2`. Value meanings: `1`: Male; `2`: Female. * `global_party_id` (_string_) The Global Party ID is set by Customer 360 and identifies a person across multiple systems. * `job_title` (_string_) The customer's job title. Maximum length: 256. * `last_login_time` (_string (date-time)_, read-only) The last login time of the customer. * `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'. * `last_name` (_string_) The customer's last name. Maximum length: 256. * `last_visit_time` (_string (date-time)_, read-only) The last visit time of the customer. * `phone_business` (_string_) The customer's business phone number. Maximum length: 32. * `phone_home` (_string_) The customer's home phone number. Maximum length: 32. * `phone_mobile` (_string_) The customer's mobile phone number. Maximum length: 32. * `preferred_locale` (_string_, read-only) The customer's preferred locale, formatted with a hyphen. (For example: en-US) If the request uses an underscore, as with the Java locale format, the stored value is converted to a hyphen. (For example: en\_US is stored as en-US) * `previous_login_time` (_string (date-time)_) The time when the customer logged in previously. * `previous_visit_time` (_string (date-time)_) The time when the customer previously visited the store. * `primary_address` (_customer\_address_) The customers primary or default address. * `salutation` (_string_) The customer's salutation. Maximum length: 256. * `second_name` (_string_) The customer's second name. Maximum length: 256. * `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr."). Maximum length: 256. * `title` (_string_) The customer's title (for example, "Mrs" or "Mr"). Maximum length: 256. _Example_ ``` { "birthday": "1970-01-31", "company_name": "Salesforce B2C Commerce", "creation_date": "2013-09-17T09:20:31.000Z", "credentials": { "enabled": true, "locked": false, "login": "dude", "password_question": "Mother's maiden name" }, "customer_no": "0815", "email": "dude@salesforce.com", "fax": "001-444-4444", "first_name": "Dude", "job_title": "", "last_name": "Lebowski", "phone_business": "001-222-2222", "phone_home": "001-111-1111", "phone_mobile": "001-333-3333", "preferred_locale": "de_DE", "salutation": "Mr.", "second_name": "second", "suffix": "suffix", "title": "Dr." } ``` ### customer\_address\_result Result document containing an array of customer addresses. * `count` (_integer (int32)_) The number of returned documents. * `data` (_array of customer\_address_) The array of customer address documents. * `next` (_string_) The URL of the next result page. * `previous` (_string_) The URL of the previous result page. * `select` (_string_) The fields that you want to select. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. * `total` (_integer (int32)_) The total number of documents. _Example_ ``` { "count": 10, "data": [ { "_resource_state": "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5", "address1": "Lodyweg", "address_id": "my_home_address", "city": "Washingtonville", "company_name": "Salesforce B2C Commerce", "country_code": "SH", "first_name": "Pit", "full_name": "Pit Snipes", "job_title": "", "last_name": "Snipes", "phone": "001-111-1111", "postal_code": "15361", "state_code": "DE" } ], "next": "https://example.com/dw/data/{version}/customer_lists/4711/customers/0815/addresses?count=10&start=10", "start": 0, "total": 151 } ``` ### customer\_address Document representing a customer address. * `address1` (_string_) The customer's first address. Maximum length: 256. * `address2` (_string_) The customer's second address value. Maximum length: 256. * `address_id` (_string_, required) The customer address id. Maximum length: 256. * `city` (_string_) The customer's city. Maximum length: 256. * `company_name` (_string_) The customer's company name. Maximum length: 256. * `country_code` (_string_, required) The customer's two-character country code per ISO 3166-1 alpha-2. Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States. Maximum length: 2. * `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'. * `etag` (_string_) * `first_name` (_string_) The customer's first name. Maximum length: 256. * `full_name` (_string_) The concatenation of the customer's first, middle, and last names and its suffix. * `job_title` (_string_) The customer's job title. Maximum length: 256. * `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'. * `last_name` (_string_, required) The customer's last name. Maximum length: 256. * `phone` (_string_) The customer's phone number. Maximum length: 32. * `post_box` (_string_) The customer's post box. Maximum length: 256. * `postal_code` (_string_) The customer's postal code. Maximum length: 256. * `salutation` (_string_) The customer's salutation. Maximum length: 256. * `second_name` (_string_) The customer's second name. Maximum length: 256. * `state_code` (_string_) The customer's state. Maximum length: 256. * `suffix` (_string_) The customer's suffix. Maximum length: 256. * `suite` (_string_) The customer's suite. Maximum length: 32. * `title` (_string_) The customer's title. Maximum length: 256. _Example_ ``` { "address1": "10 Somewhere St.", "address2": "", "address_id": "myaddress", "city": "Boston", "company_name": "", "country_code": "", "first_name": "Dude", "full_name": "Dude Lebowski", "job_title": "", "last_name": "Lebowski", "phone": "", "post_box": "", "postal_code": "", "salutation": "", "second_name": "", "state_code": "", "suffix": "", "suite": "", "title": "" } ``` ### query Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following: * match\_all\_query - returns all records. * term\_query - matches records where a field (or fields) exactly match some simple value (including null). * text\_query - matches records where a field (or fields) contain a search phrase. * boolean\_query - formulates a complex boolean expression using query objects as criteria. * filtered\_query - allows for filtering of records based on both a query and a filter. Type: `any`. ### sort Document representing a sort request. * `field` (_string_, required) The name of the field to sort on. * `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used. Allowed values: `asc`, `desc`. _Example_ ``` { "field": "id", "sort_order": "asc" } ``` ### customer\_search\_hit Document representing a customer search hit. * `data` (_customer_) The search hit data * `relevance` (_number (double)_) The hit's relevance score. _Example_ ``` { "data": { "customer_no": "000007" }, "relevance": 1.5439257621765137 } ``` ### result\_page Data that can be used to get the next and previous page of a Data API results object. * `count` (_integer (int32)_) The number of returned documents. * `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. ### cause * `cause` (_cause_) * `message` (_string_) * `type` (_string_) ### customer\_list\_preferences Document representing customer list preferences: * data-retention-age * customerno-sequence-enabled * lockout-enabled * max-failed-logins * lockout-effective-period * login-attempt-reset-time * min-password-length * min-password-special-chars * force-password-contains-alpha * force-password-contains-numeric * force-password-mixed-case * max-password-age * max-password-reset-token-age * `customer_no_sequence_enabled` (_boolean_, required) Used to determine if the customer number sequence is separated by customer list. * `data_retention_age` (_integer (int32)_, required) The number days to retain customer data (null or 0 <= x <= 99999). * `force_password_contains_alpha` (_boolean_, required) Used to determine if the password must contain an alphabetic character. * `force_password_contains_numeric` (_boolean_, required) Used to determine if the password must contain a numeric character. * `force_password_mixed_case` (_boolean_, required) Used to determine if the password must be mixed case. * `lockout_effective_period` (_integer (int32)_, required) The customer lockout period in minutes (one of 1, 30, 60, 120, 1440, 14400). * `lockout_enabled` (_boolean_, required) Used to determine if customers can be locked out. * `login_attempt_reset_time` (_integer (int32)_, required) The period after which the customer login attempt count resets in minutes (one of 0, 5, 30, 60, 120, 1440). ``` 1440) ``` * `max_failed_logins` (_integer (int32)_, required) The maximum number of failed logins before a customer lockout can occur (1 <= x <= 200). * `max_password_age` (_integer (int32)_, required) The maximum age of the customer password in days (one of 7, 10, 14, 30, 60, 90, 365000). * `max_password_reset_token_age` (_integer (int32)_, required) The maximum age of the customer password reset token in minutes (one of 30, 60, 120, 360, 720, 1440). * `min_password_length` (_integer (int32)_, required) The minimum number of characters required for a customer password (one of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 20). ``` 12, 13, 14, 15, 20) ``` * `min_password_special_chars` (_integer (int32)_, required) The minimum number of special characters required within a customer password (one of 0, 1, 2, 3, 4, 5). ### credentials Document representing the credentials of a customer. * `enabled` (_boolean_) A flag indicating whether the customer is enabled and can log. * `locked` (_boolean_) A flag indicating whether the customer account is locked. * `login` (_string_, required) The login of the customer. Maximum length: 256. * `password_question` (_string_) The password question. Maximum length: 256. _Example_ ``` { "enabled": true, "locked": false, "login": "dude", "password_question": "Mother's maiden name" } ``` ### bool\_filter Document representing a boolean filter. A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters. **Example:** (id="myId" AND coupon\_id="couponOne") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "and", filters: \[ { term\_filter: { field: "id", operator: "is", values: \["myId"\] } }, { term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } } \] } } } } **Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "or", filters: \[ { term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } }, { range\_filter: { field: "redemption\_count", from: 1, to: 20 } } \] } } } } **Example:** NOT(enabled=false OR coupon\_id="special") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { bool\_filter: { operator: "not", filters: \[ { term\_filter: { field: "enabled", operator: "is", values: \[false\] } }, { term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } } \] } } } } * `filters` (_array of filter_) A list of filters, which are logically combined by an operator. * `operator` (_string_, required) The logical operator the filters are combined with. Allowed values: `and`, `or`, `not`. ### bool\_query A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match **Example:** (id = 'foo' AND description LIKE 'bar') query: { bool\_query: { must: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** (id = 'foo' OR description LIKE 'bar') query: { bool\_query: { should: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** (NOT (id = 'foo' AND description LIKE 'bar')) query: { bool\_query: { must\_not: \[ { term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } }, { text\_query: { fields: \["description"\], search\_phrase: "bar" } } \] } } **Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false)) query: { bool\_query: { must: \[ { text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } }, { text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } } \], must\_not: \[ { term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } } \] } } * `must` (_array of query_) List of queries that must match. * `must_not` (_array of query_) List of queries that must not match. * `should` (_array of query_) List of queries that should match (i.e., at least one query must match). ### filter Document representing a filter. A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following: * term\_filter - matches records where a field (or fields) exactly match some simple value (including null). * range\_filter - matches records where a field value lies in a specified range. * query\_filter - provides filtering based on a query. * bool\_filter - provides filtering of records using a set of filters combined with a specified operator. Type: `any`. ### filtered\_query A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter. **Example:** query : { filtered\_query: { query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } }, filter: { term\_filter: { field: "enabled", operator: "is", values: \[ false \] } } } } * `filter` (_filter_, required) The (possibly complex) filter object. * `query` (_query_, required) The query object. ### match\_all\_query A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. **Example:** query: { match\_all\_query: {} } Type: `any`. ### nested\_query A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe" { "query": { "bool\_query": { "must": \[ { "nested\_query": { "path": "order.shipping\_addresses", "query": { "bool\_query": { "must": \[ { "bool\_query": { "must": \[ { "term\_query": { "fields": \[ "order.shipping\_addresses.first\_name" \], "operator": "is", "values": \[ "John" \] } } \] } }, { "bool\_query": { "must": \[ { "term\_query": { "fields": \[ "order.shipping\_addresses.last\_name" \], "operator": "is", "values": \[ "Doe" \] } } \] } } \] } }, "score\_mode": "avg" } } \] } } } * `path` (_string_, required) * `query` (_query_, required) * `score_mode` (_string_) Allowed values: `avg`, `total`, `max`, `none`. ### query\_filter Document representing a query filter. A query filter wraps any query and allows it to be used as a filter. **Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false)) query : { filtered\_query: { query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } }, filter: { query\_filter: { query: { term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] } } } } } } * `query` (_query_, required) The query to use as a filter. ### range2\_filter Document representing a range comparison with a range filter, named Range2Filter. A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to". The second range (R2) is defined by "from\_value" and "to\_value". The filter mode specifies the method used to compare the two ranges: * overlap: R1 overlaps fully or partially with R2 * containing: R1 contains R2 * contained: R1 is contained in R2 The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. **Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017) "query" : { "filtered\_query": { "filter": { "range2\_filter": { "from\_field": "valid\_from", "to\_field": "valid\_to", "filter\_mode":"overlap", "from\_value": "2007-01-01T00:00:00.000Z", "to\_value": "2017-01-01T00:00:00.000Z" } }, "query": { "match\_all\_query": {} } } } * `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap. Allowed values: `overlap`, `containing`, `contained`. * `from_field` (_string_, required) The field name of the field that starts the first range. * `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. * `to_field` (_string_, required) The field name of the field that ends the first range. * `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. ### range\_filter Document representing a range filter. A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. **Example:** ( redemption\_count BETWEEN (0,10\] ) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { range\_filter: { field: "redemption\_count", from: 0, to: 10, from\_inclusive: false } } } } * `field` (_string_, required) The search field. * `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. * `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive. * `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. * `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive. ### term\_filter Document representing a term filter. A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. **Example:** (id="my\_id") query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "id", operator: "is", values: \["my\_id"\] } } } } **Example:** (id IN ("my\_id","other\_id")) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "id", operator: "one\_of", values: \["my\_id","other\_id"\] } } } } **Example:** (description=NULL) query: { filtered\_query: { query: { match\_all\_query: {} }, filter: { term\_filter: { field: "description", operator: "is\_null" } } } } * `field` (_string_, required) The filter field. * `operator` (_string_, required) The operator to compare the field's values with the given ones. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. * `values` (_array of object_) The filter values. ### term\_query A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query . **Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. **Example:** (id="my\_id") query: { term\_query: { fields: \["id"\], operator: "is", values: \["my\_id"\] } } **Example:** (id IN ("my\_id","other\_id")) query: { term\_query: { fields: \["id"\], operator: "one\_of", values: \["my\_id","other\_id"\] } } **Example:** (id=null) query: { term\_query: { fields: \["description"\], operator: "is\_null" } } **Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword')) query: { term\_query: { fields: \["id", "description"\], operator: "one\_of", values: \["generic","keyword"\] } } * `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. * `values` (_array of object_) The values the field(s) are compared against, combined with the operator. ### text\_query A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields. **Example:** (coupon\_id contains "xmas" ) query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "xmas" } } **Example:** (coupon\_id contains "xmas" OR description contains "xmas") query: { text\_query: { fields: \["description", "coupon\_id"\], search\_phrase: "xmas" } } **Example:** (description contains "holiday" AND description contains "bojo") query: { text\_query: { fields: \["description"\], search\_phrase: "holiday bogo" } } * `fields` (_array of string_, required) The document fields the search phrase has to match. Minimum items: 1. * `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.