Search for Customer


This documentation is for translated APIs and intended only for some implementations who have upgraded from a previous version of Order Management. Verify whether your implementation uses translated APIs before making this call, as you will experience errors if your tenant is not configured to use these. If your implementation is not configured to do so, then refer to the standard API documentation instead.

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 URLhttps://{tenantId}
Sandbox URLhttps://{tenantId}
Supported FormatsJSON

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}[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}[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}[Manufacturer ID]&perPage=2&page=2


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 “,” the “a’ and hyphen would be dropped and results for other customers with email addresses like “,” “,” 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.

activeenumWhether the customer is active, inactive, or frozen.
customerIDstringA 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.
emailstringThe email of the customer. The minimum length is 1 and the maximum length is 250
firstNamestringThe customer’s first name. The minimum length is 1 and the maximum length is 300
lastNamestringThe customer’s last name. The minimum length is 1 and the maximum length is 300
phonestringThe customer’s phone number. The minimum length is 1 and the maximum length is 20.
addressstringThe customer’s street address. This can be partial; it is not required to be the entire street address.
manufacturerIDstringA single or list of unique identifiers for manufacturers. They must be positive integers.
retailerIDstringA single or list of unique identifiers for retailers. They must be positive integers.
searchStringstringA string to search over all fields. The maximum length is 150.
totalOrdersintegerThe number of orders a customer has placed.
pageintegerThe 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.

creditCardFirstFourstringThe first four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4.
creditCardLastFourstringThe last four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4.

Optional Parameters

perPageintegerThe (max) number of items to return per results page. The minimum value is “1” and the maximum value is “100”. The default is “10”.
sortBystringThe 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.


The Full Response

This is the full response returned by the API.

 "collection": [
  "active": "ACTIVE",
  "customerID": "00000000",
  "firstName": "example",
  "lastName": "user",
  "lastLogin": "2016-12-18T22:41:43+00:00",
  "phones": [
  "recentAddresses": [
  "recentOrders": [
  "totalOrders": 1