User Import APIs (POST)

how it works:

1. Trax’ User Import API V6 enables its clients to send new Users to Trax or to update existing Users in the Trax database.

2. User data should be added to a file to be sent as part of the corresponding POST request (see below). Supported file formats: Excel, CSV(semi-colon), JSON

3. User import is an async process, ie. the response contains a job ID which can be used to poll the API to get all available data incl. the status for the given upload.

4. The Excel/CSV(semi-colon)/json should/can contain the following fields (mandatory fields are marked with an asterisk *):

   1. Username*

   2. Authentication Login

   3. First Name

   4. Last Name

   5. Roles*

   6. Attribute 1-10

5. User Update Operation details

   1. Operations are done in an "update + insert" style

   2. In order to add a new User

      1. Add an object/row with all the required fields.

      2. The operation will succeed only if all the mandatory fields will be provided

   3. In order to update an existing User: 

      1. Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided 

      2. The unique identifier of a user is the 'username' field. This field is not editable

      3. Empty or missing field values will be treated as clearing the field values.

   4. In order to deactivate a User:

      1. Add an object/row with the username of the User, which serves as a unique identifier, and in addition to the rest of the mandatory fields

      2. Set the 'roles' field empty 

6. Each object/row of the file will be validated. Invalid objects/rows will be added to an error file, while the valid ones are upserted to the database.

 
Endpoints:
Request headers:
Value: 'Auth-Token {project auth token}' Authentication token provided by Trax
The default CSV delimiter is ;. To use a different delimiter (e.g., ,), include the key delimiter with the desired value in the request body. For example: "delimiter": ",".

Validate and import
POST {host}/api/v6/{project name}/account-manager/import/users
body:
file: xlsx | csv | json
 
Response: import id, example:685bf68c55fbd10009f37408
 
Only validate
POST {host}/api/v6/{project name}/account-manager/import/users/send-for-validation
body:
file: xlsx | csv | json
 
Response: import id, example:685bf68c55fbd10009f37408
 
Execute validated import
POST {host}/api/v6/{project name}/account-manager/import/users/execute/{import id}
 
Retrieve import by import id
GET {host}/api/v6/{project name}/account-manager/import/users/{import id}
 
Response:
{
 "id": "import_id_placeholder",
 "creation": "2025-06-26T12:00:00Z",
 "user": "user_id_or_email_placeholder",
 "resource": "account-manager",
 "type": "users",
 "status": "parsing",
 "fileId": "file_id_placeholder",
 "fileName": "import_file.csv",
 "rowStats": {
   "total": 100,
   "parsed": 100,
   "updated": 30,
   "created": 60,
   "deleted": 0,
   "unchanged": 10,
   "sent": 90,
   "errored": 10,
   "warnings": 0
 },
 "isAutoImport": true
}
 
 
Status description:

• parsing: the import file is being read and processed validating: validation process started but not finished validated: validation finished, import not started

• importing: importing started but not finished imported: import finished failed: the import couldn't start of finish successfully because of unexpected errors

• pending: the import file is saved and added to the queue but the parsing phase has not started yet

 
Download error file
GET {host}/api/v6/{project name}/account-manager/import/users/errors/{import id}?extension=json|csv|xlsx
 
The default extension is csv.
Response: A file stream. A csv or json or xlsx file can be downloaded that contains the failed (during validation or import) records and the related error message(s).
 
Validations:

• missing user name: User name is required

• validity of user name: User name must be a valid email or phone number

• empty roles and user creation: New user can not be created without roles

• checking the existence of roles: `Role "${role}" does not exist`

• internal role assignment for external users: `Role "${role}" is not allowed for external users`

• validity of auth email: Auth email must be a valid email

• domain check for emails and auth email: Domain is not allowed

• auth_email uniqeness: auth_email must be unique, but "${authEmail}" is already used by another user

• auth_email is the same as a user's username: auth_email must not be the same as another existing username

• same username in the file more times: "username" appears more than once in the file

• same auth_email in the file more times: "auth_email" appears more than once in the file

 
Retrieve Users list (GET)
It's possible to retrieve the Users from a project.
 
Request headers:
Value: 'Auth-Token {project auth token}' Authentication token provided by Trax
GET {host}/api/v6/{project name}/account-manager/users?limit={number}&offset={number}&enable_total={number}
 

• limit: The number of records the API returns with, the default value is 20, the maximum value is 500. 

• offset: The number of records that are skipped, the default value is 0. 

• enable_total: if true the API returns with the count of available records, the default value is false.

 
Example:
{
"metadata": {
"offset": 0,
"limit": 500,
"total": "1",
"next": "/account-manager/api/projects/{project name}/users/external?offset=500&enable_total=true",
"previous": "/account-manager/api/projects/{project name}/users/external?offset=0&enable_total=true"
   },
"data": [
       {
         "Username": "john.doe@example.com",
         "First Name": "John",
         "Last Name": "Doe",
         "Roles": "Supervisor, Viewer",
         "Attribute 1": "test1",
         "Attribute 2": "test2",
         "Attribute 3": "test3",
         "Attribute 4": null,
         "Attribute 5": "test5",
         "Attribute 6": null,
         "Attribute 7": null,
         "Attribute 8": null,
         "Attribute 9": null,
         "Attribute 10": null
       }
   ]
}


Retrieve Users Activity (GET)

 
It's possible to retrieve the Activity of users from a project.
 
Request headers:
Value: 'Auth-Token {project auth token}' Authentication token provided by Trax
GET {host}/api/v6/{project name}/account-manager/users-activity?
​

 
Example:

https://services.traxretail.com/api/v6/my-project/entity/user-activity

[

{

"pk": 1,

"email": "john.doe@customer.com",

"username": "john.doe@customer.com",

"fullName": "John Doe",

"userType": "External",

"scopeType": "Global",

"creationTime": "2020-09-02T14:09:18.000Z",

"status": "ACTIVE",

"project": "api Demo",

"roles": [

    "Mobile Users"

         ],

"consumerLicense": "-",

"additionalAttribute1": null,

"additionalAttribute2": null,

"additionalAttribute3": null,

"additionalAttribute4": null,

"additionalAttribute5": null,

"additionalAttribute6": null,

"additionalAttribute7": null,

"additionalAttribute8": null,

"additionalAttribute9": null,

"additionalAttribute10": null,

"apps": [

         {

          "app": "Mobile App",

          "lastActivity": null,

          "activity0": null,

          "activity1": null,

          "activity2": null,

          "activity3": null,

          "activity4": null,

          "activity5": null,

          "activity6": null,

          "activity7": null,

          "activity8": null,

          "activity9": null,

          "activity10": null,

          "activity11": null,

          "activity12": null,

          "activity13": null

         }

        ]

      }



 

User Hierarchy management
 

Request headers:

Value: 'Auth-Token {project auth token}' Authentication token provided by Trax

The default CSV delimiter is ;. To use a different delimiter (e.g., ,), include the key delimiter with the desired value in the request body. For example: "delimiter": ",".
 

Validate and import

POST {host}/api/v6/{project name}/account-manager/import/user-hierarchy

body:

file: xlsx | csv | json

 

Response: import id, example:685bf68c55fbd10009f37408

 

Retrieve import by import id

GET {host}/api/v6/{project name}/account-manager/import/user-hierarchy/{import id}

 

Download error file

GET {host}/api/v6/{project name}/account-manager/import/user-hierarchy/errors/{import id}?extension=json|csv|xlsx

 

The default extension is csv.

Response: A file stream. A csv or json or xlsx file can be downloaded that contains the failed (during validation or import) records and the related error message(s).

    ]