User API

The User API enables integration clients to create, activate, deactivate or configure user accounts of the instantCMR service, give or revoke permissions, provide access to the instantCMR Mobile App and the instantCMR Hub.

The user account identifier (userxtid) is a globally unique userxtid for the entity. The user account identifier can not be updated. This is also true after the user account has been deleted. Sending a PUT user request to a previously deleted user account will undelete the user account and modify its data to the user entity sent in the request body.

By assigning roles to a user account you can control what the user of the account will have access to within instantCMR.

Users with a driver role can use the instantCMR Driver App on their mobile devices to receive documents and trip assignments and to submit scans of documents and trip statuses. In order to do so they must have one or more mobile devices assigned to them on the instantCMR Hub. To assign driver role to a user account, set the roles.odriver field of the user entity to a valid Driver Role Entity. You can remove this role from the user account by removing the roles.odriver field from the user entity.

Users with the dispatcher role can use the instantCMR Hub to send documents to drivers on the Documents tab and query document scans submitted by drivers on the Inbox tab. Dispatchers can only access drivers within the same organization unit (identified by their ouxtid field). To assign dispatcher role to a user account, set the roles.odisp field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.odisp field from the user entity.

Users with the reviewer role can use the instantCMR Hub to query and drivers progress with their assigned trips and review or move document scans submitted by drivers to their assigned trips on the Trips tab. Reviewers have access to all trips regardless of the organization unit they belong to. To assign reviewer role to a user account, set the roles.orev field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.orev field from the user entity.

Users with the device inventory administrator role can use the instantCMR Hub to access user accounts and the mobile device inventory and to manage assignment of mobile devices to driver accounts. They can do so on the Users and Devices tabs. Device inventory administrators can only access drivers, that is user accounts with a driver role and no other role. To assign device inventory administrator role to a user account, set the roles.odia field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.odia field from the user entity.

Users with the chat editor role can create, add members to, remove members from, mute and unmute members of any chat group within their organization unit that they are a member of. They can do so on the Messages tab of instantCMR Hub. To assign chat editor role to a user account, set the roles.ochedit field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.ochedit field from the user entity.

Users with the chat administrator role can create, add members to, remove members from, mute and unmute members of any chat group within their organization unit. They can also search for, read and post messages into chat groups that they are not a member of. They can do so on the Messages tab of instantCMR Hub. To assign chat administrator role to a user account, set the roles.ochadmin field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.ochadmin field from the user entity.

Users with the campaign administrator role can create, edit, and archive gamification campaigns. They can also manage campaign details such as name, description, metrics, date range, and participants. Campaign administrators can view and update ongoing campaigns, monitor scores as needed. They can perform these actions on the Campaigns tab of instantCMR Hub. To assign the campaign administrator role to a user account, set the roles.campaignadmin field of the user entity to an empty object ({}). You can remove this role from the user account by removing the roles.campaignadmin field from the user entity.

Users with the integration endpoint role can use the instantCMR API to manage trips, user accounts and their assignments and to subscribe to updates on trip, user and submitted documents. You cannot assign or unassign integration endpoint role to a user account via the instantCMR API and attempting to do so will yield a 403 Forbidden http status code. Updating a user account that has integration endpoint role via the instantCMR API is also forbidden. Should you need further user accounts with integration endpoint access please contact our customer support at help@instantcmr.com.

Users with access to the instantCMR Hub will need a login name to log in. The login name consists of an account name (oaccn), the ‘@’ (at) symbol and the company id (copid) of the user entity.

Example: if the company id is LogisticsGmbh and the user’s account name is bertram.friedrich then the user can login on the instantCMR Hub with the login name betram.friedrich@LogiscticsGmbh.

To provide an account name for a user account, set the oaccn field to the account name. Note that you can not set the company id as it is set by our customer support when creating a company account for you.

The provided account name must be globally unique and may consist only of letters, digits, the ‘.’ (dot) and ‘-’ (dash) characters. Sending a PUT user request with a clashing account name or containing invalid characters will result in a 400 BadRequest http status code.

If you send a PUT user request for a user having access to the instantCMR Hub without providing an account name (oaccn), an account name will be generated for the user based on its user name (usern) field. Should the generated account name collide with another account name the request will yield a 400 BadRequest status code.

You can set up various email addresses that instantCMR uses to send incoming document notifications, password reset emails and account invite emails to. Please note that all email addresses must pass the pre-authorization check in order to the PUT user request succeed. If any email addresses included in the user entity fail the pre-authorization checks, the request will fail with a 400 BadRequest http status code.

See Anti-Spam requirements for email contacts for further details.

Each user account is provided with a document storage area that can be used by dispatchers to share documents with drivers or other instantCMR user accounts. This is true even for user accounts with no further roles assigned.

In order to subscribe a user’s account to another user’s document storage, include the userxtid of the sharing user into the dboxc.rguserxtidFollow field of the subscribing user account’s user entity. All documents uploaded to the sharing user’s document storage (or any document storage the sharing user is subscribed to) will also appear in the subscriber user’s document storage both on instantCMR Hub and the user’s mobile devices.

A user account can be deactivated by updating its ofDeleted field to true, or by sending a DELETE user request. Deactivated users will be unable to login to the instantCMR Hub or submit documents and receive trip updates on their mobile devices.

instantCMR will keep all historical data of deactivated users and make them available for examination on the instantCMR Hub.

A previously deactivated user account can be reactivated by removing its ofDeleted field.

GET /v3/igr/user/{copid}/{userxtid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{usered}

PUT /v3/igr/user/{copid}/{userxtid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/json  
[If-Match: {ETag}]  
[If-None-Match: *]  
Content-Length: 1779  

{usereu}

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag}  
Content-Length: 1386  

{usered}  

DELETE /v3/igr/user/{copid}/{userxtid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag}
Content-Length: 1386  

{usered}