Users V5
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 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/v5/my-project/entity/user?sort=email_address
Request Details
Query Parameters
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
version_number string *
The current implemented API version. <Major> version (in this case '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
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
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=0
per_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",
"first_name":"Henry",
"last_name":"Ford",
"is_deleted":false,
"operational_role":"Sales Rep",
"entities":{
"routes":[
"route1",
"route2",
"route3",
"12345",
"USER@EXAMPLE.com"
]
}
},
{
"login_name":"097255555555",
"mobile_number":"+97255555555",
"first_name":"John",
"last_name":"Doe",
"is_deleted":false,
"operational_role":"Supervisor",
"entities":{
}
}
]
}
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>
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
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 for an already existing user. 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 stores lists value will be parsed from a quoted comma-separated value (e.g. the array ["4", "2"] will be written as "4,2")
-
Request Example
Assume that Trax already contains valid data for 2 users:
User POST Request File Fields
Mandatory fields marked indicated by
*
Request Example - CSV
login_name, first_name, last_name, default_role, status, operational_role
ford@example.com, Henry Ford, API (External Role), active, Sales Rep
Request Example - JSON
[
{
"login_name": "ford@example.com",
"first_name": "Henry",
"last_name": "Ford",
"default_role": "API (External Role)",
"status": "active",
"operational_role":"Sales Rep",
"supervisor_username": null,
"position" null
},
{
"first_name": "John",
"last_name": "Doe",
"email_address": "john@example.com"
},
{
"first_name": "Sally",
"last_name": "Housecoat",
"email_address": "sally@example.com"
}
},
{
"first_name": "John",
"last_name": "Smith"
}
}
]
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" will be added as a Sales Rep
-
John Doe will be disabled
-
Sally Housecoat will get a new role
Please note that changing a user's status to DISABLED he/she will be disabled in general, ie. not only for the project where this has been requested, but for all Trax projects.
login_name string *
User's user name. It can be either a universally unique email address or phone number. If one of the items added later (eg user initially created with email and mobile number is added later), then the identifier originally used to create the account is the unique identifier
first_name string
User's first name
last_name string
User's last name
default_role string *
The role the user should have when the user account is instantiated. It should come from the preexisting list of roles that exist for users in your project. For a full list see the excel upload template
status string
User's status. Active, Disabled, or Pending. Pending is the state between when they have been added and when they have validated their login credentials
operational_role string
Discovery ops Employee's role (e.g. Sales Rep, Supervisor, etc)
supervisor_name string
Discovery supervisor's username
position string
Discovery's user position
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"
]
}
]