Introduction to Users

4min

A User represents the human resource that performs a task or a set of tasks such as pick-up, delivery, and operations management. Users perform various assigned roles, such as operator, supervisor, and manager.
You can use the User API to build apps that can onboard and manage Users in your customer’s Organization.
User lifecycle
By default, a User has four lifecycle states:
Onboarding - User data is being entered and/or verified.
Active - ​​User data is verified and the User is activated.
Deboarding - The User is in the process of being deactivated (for example, serving a notice period).
Inactive - The User has been deactivated.
To retrieve the current state of a USER, call the Get User State endpoint.
The response body is returned in JSON format:
JSON
{
  "error": {
    "code": "string",
    "description": "string"
  },
  "request": {
    "uri": "string",
    "body": {}
  },
  "data": {
    "event": {
      "toState": "active:available",
      "reasonCode": "R-104",
      "data": {}
    },
    "id": "user:e5f2064c-1a8c-45d9-b125-05a5416135c9",
    "state": "active:available"
  }
}
{
  "error": {
    "code": "string",
    "description": "string"
  },
  "request": {
    "uri": "string",
    "body": {}
  },
  "data": {
    "event": {
      "toState": "active:available",
      "reasonCode": "R-104",
      "data": {}
    },
    "id": "user:e5f2064c-1a8c-45d9-b125-05a5416135c9",
    "state": "active:available"
  }
}
﻿
To change the state of a User, call the User State Transition endpoint and pass the following parameters in the request body:
Member
Description
toState
One of the valid state codes: onboarding, active, deboarding, or inactive.
reasonCode (optional)
A valid reason code associated with the event.
data (optional)
Any additional information about the transition.
Request bodies are specified in JSON format. The following example request body shows how to change the state of the User:
JSON
{
  "toState": "active:available",
  "reasonCode": "R-104",
  "data": {}
}
{
  "toState": "active:available",
  "reasonCode": "R-104",
  "data": {}
}
﻿
User Attributes
Attributes describe the characteristics of an object in the platform. The User API specifies a set of system-defined attributes and allows for the creation of Custom Attributes.
The following Attributes are defined by default for each User in the system:
Attribute
Description
Data type
firstName
(required)
The first name of the User.
String
middleName
The middle name of the User.
String
lastName
The last name of the User.
String
designation
(required)
The Organizational title or position assigned to a User. To fetch default designations, use the GET All Designation endpoint.
String
email
The email address of the User.
String
category
(required)
The User type within the organization.Values: Regular or Adhoc.
String
primaryMobile
(required)
The primary mobile number of the User.
VarChar
primaryMobile >
countryCode
(required)
Standard country code for primary mobile number
String
primaryMobile > 
number
(required)
The mobile number of the User. It should be valued between 4 - 10 numeric digits.
String
secondaryMobile
The secondary mobile number of the User. This is a structure consisting of two fields: the country code and the mobile number.
VarChar
employmentType
(required)
The employment type of the User.Values: Full-time, Part-time, Contract/ Adhoc, or N/A.
String
workLocations
An array of work locations for the user. Example: facilities:1238-232-dsfs23-sdsdc
String
manager
The Participant ID of the User’s supervisor.
String
identification
The type of identification document used to validate the User.Valid values: Drivers license, Passport, PAN card, Aadhar card, or VoterID.
String
subFunction
The subfunction of the user.
String
fileID
The file ID of a picture of the user in the File Management System. 
Example: file:1238-232-dsfs23-sdsdc
String
﻿

Member	Description
toState	One of the valid state codes: onboarding, active, deboarding, or inactive.
reasonCode (optional)	A valid reason code associated with the event.
data (optional)	Any additional information about the transition.

Attribute	Description	Data type
firstName (required)	The first name of the User.	String
middleName	The middle name of the User.	String
lastName	The last name of the User.	String
designation (required)	The Organizational title or position assigned to a User. To fetch default designations, use the GET All Designation endpoint.	String
email	The email address of the User.	String
category (required)	The User type within the organization.Values: Regular or Adhoc.	String
primaryMobile (required)	The primary mobile number of the User.	VarChar
primaryMobile > countryCode (required)	Standard country code for primary mobile number	String
primaryMobile > number (required)	The mobile number of the User. It should be valued between 4 - 10 numeric digits.	String
secondaryMobile	The secondary mobile number of the User. This is a structure consisting of two fields: the country code and the mobile number.	VarChar
employmentType (required)	The employment type of the User.Values: Full-time, Part-time, Contract/ Adhoc, or N/A.	String
workLocations	An array of work locations for the user. Example: facilities:1238-232-dsfs23-sdsdc	String
manager	The Participant ID of the User’s supervisor.	String
identification	The type of identification document used to validate the User.Valid values: Drivers license, Passport, PAN card, Aadhar card, or VoterID.	String
subFunction	The subfunction of the user.	String
fileID	The file ID of a picture of the user in the File Management System. Example: file:1238-232-dsfs23-sdsdc	String

Updated 03 Aug 2023

Did this page help you?

User API

Creating Users