Introduction to Users

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 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:

{
  "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

Remarks

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:

{
  "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

Remarks

firstName
(required)

The first name of the User.

middleName
(required0

The middle name of the User.

lastName

The last name of the User.

function

The job role within an Organization.

These are Organization specific values. For more information, see User Functions.
User Attributes.

designation
(required)

The Organizational title or position assigned to a User.

For more information, see Designation.

email

The email address of the User.

category

The User type within the organization.

Valid values are: Regular or Adhoc.

primaryMobile
(required)

The primary mobile number of the User.

This is a structure consisting of two fields: the country code and the mobile number.

secondaryMobile

The secondary mobile number of the User.

This is a structure consisting of two fields: the country code and the mobile number.

employmentType
(required)

The employment type of the User.

Valid values are: Full-time, Part-time, Contract/ Adhoc, or N/A.

workLocations

An array of work locations for the user.

manager

The Participant ID of the User’s supervisor.

identification

The type of identification document used to validate the User.

Valid values: Drivers license, Passport, PAN card, Aadhar card, or VoterID.

subFunction

The subfunction of the user.

fileID

The file ID of a pictures of the user in the File Management System.


Did this page help you?