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.
API documentation: https://motimate.motimateapp.com/public_api/docs
API Access: To request authorization details for your MotiSpace, please contact either your Customer Success manager or support@motimateapp.com
Understanding the API
- An employee in Motimate is referred to as a user. Both users and groups will have their own external ID which you can use to update or make changes. This ID typically matches up with the ID you have for that user or group in your data source.
- Groups are used to create an org structure through which you can 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.
- A user's Position allows you to delegate training based on their role at the organization. This is more than often used when there are Positions that are commonly used throughout the organization. This article will not describe how to create positions.
- You can see all available API calls in our documentation. In order to test calls in this UI, you will need to obtain an access token. This is done by entering your Client ID and Secret in the POST/oauth/token call.
- 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.
- All fields in Motimate are set by default and cannot be customized. These include fields such as "first_name", "last_name", and "email".
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, that 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}?identifier_type=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}?force=1&identifier_type=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