Search Customer Address Information


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 Address API allows the user to find a particular address based on a number of variables. Either the Customer ID or Address ID must be known to perform the search.

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}{parameters}
Sandbox URLhttps://{tenantId}{parameters}
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 an address of a particular customer that is associated to a manufacturer would use the following format:

  • https://{tenantId}[Customer ID]&manufacturerID=[Manufacturer ID]

In the case of performing a search with multiple terms of the same parameter, such as retrieving multiple customer IDs at once, use a comma-separated list as shown below.

  • https://{tenantId}[Customer ID One],[Customer ID Two],[Customer 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}[Customer ID]&perPage=2&page=2


In this example, the customer address being searched for includes these particular properties:

  • Searching for address of Customer 333222111
  • Customer is known to be active
  • Street address is both billing and shipping

Required Parameters

One of two IDs needs to be known to search for an address. The API call always requires at least one of these data points to reference as a search term:

addressIDstringA unique identifier for the address, usually an integer. The minimum length is 1.
customerIDstringA unique identifier for the customer, usually an integer. The minimum length is 1.
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.

Optional Parameters

An address may not always have the following data points designated, but it is possible to use them to filter search results:

manufacturerIDstringA single or list of manufacturerIDs, which must be positive integers. The minimum length is 1.
catalogIDsstringA single or list of catalogIDs, which must be positive integers. The minimum length is 1.
retailerIDstringA single or list of retailerIDs, which must be positive integers. The minimum length is 1.
activebooleanWhether to search from active customers (true) or include inactive customers (false). The default is “true”.
perPageintegerThe (max) number of items to return per 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 customer addresses 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": [
  "addressID": "1122333",
  "customerID": "333222111",
  "firstName": "example",
  "lastName": "customer",
  "addressLine1": "000 CUSTOMER LN",
  "phone": "00000000000",
  "city": "DALLAS",
  "state": "TX",
  "postalCode": "75201",
  "countryCode": "US",
  "fraudLock": false,
  "active": true,
  "latitude": 38.6329,
  "longitude": -119.826,
  "isBilling": true,
  "isShipping": true