Users V4
In the context of Authentication & On-Device Integrations, the users will be added with permissions to Trax mobile application, and will be connected to a list of stores/routes. The affiliation of a user with a store/route grants the ability to perform a store visit via the mobile application.
Querying users from Trax
Creating, Deleting, and Updating users in Trax in an asynchronous way
GET
Supported Protocol: HTTPS
GET /api/:version_number/:project_name/entity/user?:pagination_params
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/entity/user?sort=email_address
Request Details
Mandatory fields marked indicated by
*
Response Details
login_name string
User's login name
email_address string
A valid, working, email, that is universally unique
mobile_number string
A valid, working, mobile number that is universally unique and in use,
e.g. +447813988839
first_name string
User's first name
last_name string
User's last name
is_deleted Boolean
True/False
supervisors_username string
The username (email/telephone) of the supervisor of the user
operational_role string
The user's operational role. The optional values are: Sales Rep, Auditor, Supervisor, Manager
entities Object[]
List of entities that are linked to the user:
routes string[] List of external_route_id that are linked to the user
stores string[] List of store_numbers that are linked to the user
The User GET reply body will contain the following fields:
{
"metadata": {
"page": 2,
"per_page": "10",
"page_count": 1167,
"total_count": 11668,
"links": {
"self": "/api/v4/my-project/entity/
user?sort=email_address&
page=1&per_page=10",
"first": "/api/v4/my-project/entity/
user?sort=email_address&
page=0per_page=10",
"previous": "/api/v4/my-project/
entity/user?
sort=email_address&
page=0&per_page=10",
"next": "/api/v4/my-project/entity/user
?sort=email_address&page=2
&per_page=10",
"last": "/api/v4/my-project/entity/user
?sort=email_address&page=1
166&per_page=10",
}
},
"users": [
{
"login_name": "ford@example.com",
"email_address": "ford@example.com",
"mobile_number":"+15417543010",
"first_name": "Henry",
"last_name": "Ford",
"is_deleted": false,
"supervisors_username": "john@example.com",
"operational_role": "Sales Rep",
"entities": {
"routes": [ "CB1" ]
}
},
{
"login_name": "john@example.com",
"email_address": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"is_deleted": false,
"operational_role": "Supervisor",
"entities": {
"routes": [ "A365" ]
}
},
{
"login_name": "sally@example.com",
"email_address": "sally@example.com",
"first_name": "Sally",
"last_name": "Housecoat",
"is_deleted": false,
"operational_role": "Sales Rep",
"entities": {
"routes": []
}
},
{
"login_name": "+447813988839",
"mobile_number": "+447813988839",
"first_name": "John",
"last_name": "Smith",
"is_deleted": false,
"operational_role": "Manager",
"entities": {
"routes": ["route_A"]
}
},
{
"login_name": "smith@example.com",
"email_address": "smith@example.com",
"first_name": "Dana",
"last_name": "Scully",
"is_deleted": false,
"operational_role": "Auditor",
"entities": {
"stores": ["100","200","300"]
}
}]
}
Response
Unknown Field
-
Error Code: 400 - Bad Request
-
Error: Unknown Field: <field_name>
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Incorrect or expired token
-
Error Code: 401 - Unauthorized
-
Error: Incorrect or expired token
Requesting a forbidden resource
-
Error Code: 403 - Forbidden
-
Error: A forbidden resource has been requested <resource>
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
pagination params
For more info see the Pagination page. By default the first page will be returned first
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
POST
Creating, Deleting, and Updating users in Trax is done asynchronously. The users POST should be done via the Async jobs framework using the information below. In the context of Authentication and & On-Device Integrations, the users will be added with permissions to the Trax Mobile Application, and will be connected to a list of stores/routes. The affiliation of a user with a store/routes grants the ability to perform a store visit via the mobile application.
User Update Operation Details
Operations are done in an "update + insert" style:
-
In order to add a new user:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
-
In order to update a user:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
Empty field values will be treated as setting a field value to null
-
In CSV, the user's list's value will be parsed from a quoted comma-separated value (e.g., the array ["4","2"] will be written as " 4, 2")
-
-
In order to delete a user:
-
Add an object\row with the login_name of the user, which serves as a unique identifier
-
Add a value for 'is_deleted'
-
Deleting a mobile user will prevent the user from logging in to Trax mobile app (via deep link pending token expiry policy).
-
Request Example
Assume that Trax already contains valid data for 3 users:
In the JSON and the CSV examples below, the following effect will occur on the data that is stored in Trax:
-
A new user, Henry Ford, with email "ford@example.com" and a relation to the "400" store will be added
-
John Doe will be deleted from Trax systems
-
Sally Housecoat will gain a relation to the "300" store, and gain a relation to the "route_1" and "route_2" and "route_3" routes.
-
John Smith will lose its relation to the "200" store and 400" store, and gain a relation to the "route_A"
User POST Request File Fields
first_name string *
User's first name
last_name string *
User's last name
email_address string *
A valid, working, email, that is universally unique
mobile_number string *
A valid, working, mobile number, that is universally unique and in use
Note: Only one between email_address or mobile_number is needed. Whichever one is used in the initial setup will be the unique identifier used for that user and no additional identifiers can be added later. For example, if an email_address was sent in the initial setup, a mobile_number cannot be added later on. If both are provided in the initial setup then the email_address will be used by default as the username
store_numbers string[]
An array of store numbers that are linked to this user. There is a many-to-many relation between mobile users and stores. Each Store number must be an active store as listed in Trax (See STORES-POST-Async). A mobile user will not be able to perform a store visit if it is not related to this store
Note: While this behavior is supported, the recommended method for connecting users to stores is to first import Users and Stores separately using Async-Jobs (see Stores-POST-Async and see Users-POST on this page), then connect them using routes (see Routes-POST-Async)
is_deleted Boolean
True - delete the user
False - remove the delete flag - By default false
entities Object[]
List of entities that are linked to the user
routes string[]
An array of external_route_id that are linked to this user. There is a many-to-many relationship between mobile users and routes. Each external-route-id must be an active route as listed in Trax (see Routes-POST-Async)
*
Request Example - CSV
first_name,last_name,email_address,store_numbers,is_deleted,entities.routes,mobile_number
Henry,Ford,ford@example.com,"400",,,,, John,Doe,john@example.com,,true,,,,
Sally,Housecoat,sally@example.com,,,"route_1,route_2,route_3"
John,Smith,,,,route_A,,,+447813988839
Request Example - JSON
[
{
"first_name": "Henry",
"last_name": "Ford",
"email_address": "ford@example.com", "store_numbers": [ "400" ]
},
{
"first_name": "John",
"last_name": "Doe",
"email_address": "john@example.com", "is_deleted": true
},
{
"first_name": "Sally",
"last_name": "Housecoat",
"email_address": "sally@example.com",
"entities": {
"routes": ["route_1", "route_2", "route_3"]
}
},
{
"first_name": "John",
"last_name": "Smith",
"mobile_number": "+447813988839",
"entities": {
"routes": ["route_A"]
}
}
]
Mandatory fields marked indicated by
Response, Validation, and Errors
The initial response for a valid async job request will be 202 Accepted.
When the async job is queried, the outcome of the job will be available only when the status is 'done'.
For more info, see the Async-Jobs page
Validation and Error File
When uploading the file, the Trax system runs numerous validations on the file to confirm it has all the necessary fields.
Should there be issues with the file, an error file will be generated. It will contain one or several of the following errors based on failing the related validation:
Mandatory Variables - Missing Mandatory
Fields During creation
-
Missing mandatory field:<field_name>
-
Missing mandatory fields:
<field_name>,<field_name>....
Variable Types
-
Invalid variable type:<field_name>-expected type: <expected_variable_type>
-
Invalid variable types:<field_name>-expected type: <expected_variable_type>,
<field_name>-expected type: <expected_variable_type>...
Incorrect Format - Email Format will be validated
-
Incorrect format for field: <field_name>, the correct format: <correct_format>
Lookup Value does not exist, Unknown Value
-
Unknown <Look Up Type> '<Look Up Value>'
-
Example: Unknown Store <request_store_identifier>
(store_number as referenced in store_numbers)
-
Error File Example
[
{
"email_address": "ford@example.com",
"errors": [
"missing attribute-first_name",
"Unknown values store_numbers:400"
]
},
{
"email_address": "sally@example.com",
"errors": [
"Unknown values store_numbers:100"
]
},
{
"mobile_number":"+447813988839",
"errors": [
"Unknown values store_numbers:300,400"
]
}
]