The Search Customer API allows the user to find a particular customer based on a number of variables.
Note that the parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.
| Production URL | https://{tenantId}-translation.mozu.com/api/v2/customer/ |
| Sandbox URL | https://{tenantId}-translation.sandbox.mozu.com/api/v2/customer/ |
| Supported Formats | JSON |
| HTTP Method | GET |
The request itself is built within the URL by adding a “/?” to the call followed by specific parameters joined by the “&” symbol. For instance, searching for a customer with a particular first name from a specific manufacturer would use the following format:
- https://{tenantId}-translation.mozu.com/api/v2/customer/?firstName=[Name]&manufacturerID=[Manufacturer ID]
In the case of performing a search with multiple terms of the same parameter, such as retrieving multiple manufacturer IDs at once, use a comma-separated list as shown below.
- https://{tenantId}-translation.mozu.com/api/v2/customer/?manufacturerID=[Manufacturer ID One],[Manufacturer ID Two],[Manufacturer ID Three]
GET calls that support pagination for numerous results, such as when searching, also accept a perPage parameter that defines how many results can be returned on each page. The default is 10 and the maximum is 100. Switch between pages of results by appending the page parameter to the call. For example:
- https://{tenantId}-translation.mozu.com/api/v2/customer/?manufacturerID=[Manufacturer ID]&perPage=2&page=2
Example
In this example, the customer being searched for includes these particular properties:
- Searching for customer based on their email
- Resultant customer is Active, with one recent order
Required Parameters
A variety of possible properties can be used to locate an existing customer. The API call always requires at least one of the data points listed below to reference as search terms.
Note that this API will break down search terms such as email addresses based on punctuation and stopwords, meaning that similar results may be returned rather than exact matches. For instance, in a query based on an email address of “a-smith@gmail.com,” the “a’ and hyphen would be dropped and results for other customers with email addresses like “john-smith@gmail.com,” “jane-smith@gmail.com,” etc. would be returned. There is no filter that can be utilized to request for exact matches only, so it is best to provide multiple parameters when searching for a customer. Querying based on email, first name, and last name has a higher likelihood of returning the desired result rather than only based on email or a single name parameter.
| Parameter | Type | Description |
| active | enum | Whether the customer is active, inactive, or frozen. |
| customerID | string | A unique customer identifier, usually an integer. The minimum length is 1. Note that this value is an internal identifier assigned by OMS, not the external customer ID. |
| string | The email of the customer. The minimum length is 1 and the maximum length is 250 | |
| firstName | string | The customer’s first name. The minimum length is 1 and the maximum length is 300 |
| lastName | string | The customer’s last name. The minimum length is 1 and the maximum length is 300 |
| phone | string | The customer’s phone number. The minimum length is 1 and the maximum length is 20. |
| address | string | The customer’s street address. This can be partial; it is not required to be the entire street address. |
| manufacturerID | string | A single or list of unique identifiers for manufacturers. They must be positive integers. |
| retailerID | string | A single or list of unique identifiers for retailers. They must be positive integers. |
| searchString | string | A string to search over all fields. The maximum length is 150. |
| totalOrders | integer | The number of orders a customer has placed. |
| page | integer | The page number to begin listing the results from. The default and minimum value is “1”. While this parameter is technically required, this default means that it does not have to be provided in the request unless a different page is specifically desired. Also, note that the page cannot be the sole parameter in the search query – if provided, there must be at least one of the other parameters in this table. |
The customer can also be searched for by their credit card number, but both of the associated values listed below depend on each other and thus must always be provided together.
| Parameter | Type | Description |
| creditCardFirstFour | string | The first four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4. |
| creditCardLastFour | string | The last four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4. |
Optional Parameters
| Parameter | Type | Description |
| perPage | integer | The (max) number of items to return per results page. The minimum value is “1” and the maximum value is “100”. The default is “10”. |
| sortBy | string | The field(s) to sort results by, use a minus (-) in front of field name for descending, a plus (+) for ascending. The minimum length is 1. |
The Full Request
Using the URL format as outlined above, the entire call is fairly simple to put together. This sample will search for customers matching the example’s parameters. Any amount of additional parameters could be appended if desired.
https://{tenantId}-translation.mozu.com/api/v2/customer/?email=example.user@shopatron.comThe Full Response
This is the full response returned by the API.
{
"collection": [
{
"active": "ACTIVE",
"customerID": "00000000",
"email": "EXAMPLE.USER@SHOPATRON.COM",
"firstName": "example",
"lastName": "user",
"lastLogin": "2016-12-18T22:41:43+00:00",
"phones": [
"1110000000",
"2220000000"
],
"recentAddresses": [
"111 TEST STREET, NEW YORK, US"
],
"recentOrders": [
0123456
],
"totalOrders": 1
}
]
}