Motimate: How to use public API to provision and manage users and groups?

You can provision and manage users in Motimate by connecting your source system to our REST API. This enables you to handle several core jobs in Motimate like creating users, updating users, deleting users, creating groups and provisioning users to the correct groups. 

Background information: 

• All users and groups have their unique Motimate IDs which can be used with the API, but you can also define an 'external ID' which you can use with the API. This 'external ID' is typically set to match up with the ID you have for that user or group in your own data source. 
   
• Groups are used to create a hierarchy or group tree. This will usually closely mirror your organization structure, and is used to delegate training and obtain reports. This is often based upon either departments and teams, or regions. We recommend creating groups before creating users so that you can assign users directly to groups upon creation. See here for more information on group structure.
   
• A user's Position allows you to delegate training based on their role at the organization. See here for more information on user Positions.
   
• We recommend setting up a test environment to test your calls and integration as a whole, before transferring to your production environment. Please contact your Customer Success Manager or support@motimateapp.com for assistance. 
   
• Motimate's API is in JSON format. 

Creating groups

To create groups use the following call: 
POST https://motimateapp.com/public_api/groups

Add the payload to the body with the necessary information with the group. The "parent_id" field is used to create a group structure. Entering the ID of a different group in this field will set that group as the parent.

Please note: the level of the group must be in the lower hierarchy than the parent group, with "Level 1" being the highest level. This allows you to import group structures into your Motimate account. 

Updating groups 

In order to update a group in Motimate you will need the following call. The id used in this example is the Motimate group id. 

PATCH https://motimateapp.com/public_api/groups/{group_id}

Add payload to the body with the necessary data you wish to update on the Groups. This can be used when a Group needs to be moved to a different level or if the structure needs to be adjusted. 

 

Deleting groups

In order to delete a group in Motimate you will need the following call. The id used in this example is the Motimate group id. Setting force to ´1´ will hard destroy the record, there is no way to recover the group in this scenario.

DELETE https://motimateapp.com/public_api/groups/{group_id}

Running this call will delete the selected group, although a response is not returned: 

 

Creating Users

To create users, use the following call: 

POST https://motimateapp.com/public_api/users

Add the payload to the body with the necessary information of the user. Either the email address or phone number will be a mandatory field depending on your Motimate account settings. You can select the user's Groups by using the group assignments field. Enter the Group id that you want the user to be a part of and their role in the group (member, admin, or observer). We recommend setting assing_ancestors to 'true' in the vast majority of scenarios. This ensures that users will be members of the parent groups of their assigned groups. 

 

Updating Users

In order to update a user's information in Motimate you will need the following call. The id used in this example is the Motimate user id. 

PATCH https://motimateapp.com/public_api/users/{user_id}?identifier_type=id

Add payload to the body with the only necessary data you wish to update for the user. 

 

Deleting Users

In order to delete a user in Motimate you will need the following call. The id used in this example is the Motimate user id. Setting force to ´1´ will hard destroy the record, there is no way to recover the group in this scenario. Setting it to ´0´ will soft delete the record, allowing it to be recovered if necessary. 

DELETE https://motimateapp.com/public_api/users/{user_id}?force=1&identifier_type=id

Running this call will delete the selected user, although a response is not returned: 

Restoring Users

Sometimes a user is deleted by mistake and needs to be restored. If they have been soft deleted, and not hard destroyed, this can be done with the following call. The id used in this example is the Motimate user id. 

PATCH https://motimateapp.com/public_api/users/{user_id}/restore?identifier_type=id