OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

Search for User

The Search User API allows the admin to find a particular user based on a number of variables.

Version2.0
Callhttps://integration.shopatron.com/api/usermgmt/v1/user
Supported FormatsJSON
HTTP MethodGET
Schemahttps://integration.shopatron.com/api/usermgmt/v1/schema/userSearch.json

Note that the core URL may be different from the standard production environment, depending on the configuration.

The .json address above can be used to access the schema within Postman. An example use of the User Management API follows below, or view the sample Postman collection.

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 user based on their first and last names would use the following format:

  • https://integration.shopatron.com/api/usermgmt/v1/user/?firstName=[First Name]&lastName=[Last Name]

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

  • https://integration.shopatron.com/api/v2/user/?userID=[User ID One],[User ID Two],[User 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://integration.shopatron.com/api/v2/user/?firstName=[First Name]&perPage=2&page=2

Example

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

  • Searching for users based on the first name “Example”
  • Two results, one Manufacturer Admin and one System Admin

Required Parameters

The “active” parameter must always be required, in addition to at least one of the other datapoints listed below to reference as a search term:

ParameterTypeDescription
userIDintegerA unique identifier for the user. The minimum value is “1”.
groupIDintegerA unique identifier for the group that the user is assigned to. The minimum value is “0”.
firstNamestringThe first name of the user. The maximum length is 50.
lastNamestringThe last name of the user. The maximum length is 50.
fullNamestringThe full name of the user. This combines the firstName and lastName parameters.
emailstringThe email of the user. The maximum length is 70.
catalogIDintegerA unique identifier for the catalog that the user is assigned to. The minimum value is “0”.
usernamestringThe unique username of the user. The maximum length is 50.
phonestringThe phone number of the user. The minimum length is 6 and the maximum length is 20.
locationIDintegerA unique identifier for the fulfillment location that the user is assigned to. The minimum value is “1”.
manufacturerIDstringA unique identifier for the manufacturer that the user is assigned to.
retailerIDstringA unique identifier for the retailer that the user is assigned to.
activeboolean Whether the user is active or not. The default is “true”.

Optional Parameters

The following parameters may also be provided.

ParameterTypeDescription
perPageinteger 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”.
pageinteger The page number to begin listing the results from. The default and minimum value is “1”, so it will be automatically set as 1 even if not provided in the search request.
sortBystring 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 users matching the example’s parameters. Any amount of additional parameters could be appended if desired.

https://integration.shopatron.com/api/usermgmt/v1/user/?firstName=Example

The Full Response

This is the full response returned by the API. This search returned two results, each represented by their own block of data.

{
 "collection": [
 {
  "userID": 11211,
  "username": "example1",
  "firstName": "Example",
  "lastName": "Userone",
  "email": "example1@shopatron.com",
  "active": 1,
  "passwordExpires": "2017-10-14T00:24:58+00:00",
  "lastLogin": "2017-08-01T22:29:48-07:00",
  "groupID": 2,
  "groupName": "Manufacturer Admin",
  "manufacturerID": 000,
  "fulfillerID": 00000,
  "locale": "en-US",
  "admin": 0
 },

 {
  "userID": 22122,
  "username": "example2",
  "firstName": "Example",
  "lastName": "Usertwo",
  "email": "example2@shopatron.com",
  "active": 1,
  "passwordExpires": "2018-01-15T02:28:12+00:00",
  "lastLogin": "2017-11-01T22:01:06-07:00",
  "groupID": 1,
  "groupName": "System Admin",
  "retailerID": 111,
  "fulfillerID": 11111,
  "locale": "en-US",
  "admin": 0
  }
 ]
}