top of page

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

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

[

{

"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", "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"]

}

}

]

In the JSON and the CSV examples below, the following effect will occur on the data that is stored in Trax: 

  1. A new user, Henry Ford, with email "ford@example.com" will be added as a Sales Rep

  2. John Doe will be disabled

  3. 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"

]

}

]

bottom of page