Overview
The Mobaro API lets your HR, IT or identity system keep Mobaro's Users, User Groups and Roles in step with your own records: create starters, update changed details, disable leavers and manage group membership, without typing it all into the Backend.
This article covers what each endpoint accepts and the traps to avoid in a sync. For creating Users by hand, see Create new users in your organization.
At a glance |
|
Who can do this | An integration with an API key. Reading works with a Read-only key; creating, updating and deleting need a key that isn't Read-only. |
Where |
|
Works on | Public API. Changes apply in the Backend (web), Mobile app and RideOps. |
Availability | API access, enabled per organization by Mobaro — ask your CSM |
What the API can manage
Record | You can | You can't |
Users | List, get, create, update, disable, delete | Make a User a Super User, give them Roles, User Groups or Locations from the User record, or change their notification settings |
User Groups | List, get, create, update, delete, add or remove members | Change a group's Require single sign-on after it's created, or its Locations from the group endpoint |
Roles | List, get, rename, change which Users and User Groups have the Role, delete | Create a Role or read or change its permissions |
A User's Roles and group memberships are set from the Role and the User Group. After a group is created, its Location access is set from the Location or Location Group (relations endpoints, Beta): see Importing Locations via the Mobaro API. To understand how these combine, see How access works in Mobaro.
Sync Users from another system
1. Look up the User
Send GET /api/customers/users/{id}. Instead of the Mobaro ID you can use the User's External ID or email address. You get 404 Not Found if no User in your organization matches. GET /api/customers/users lists everyone, and accepts CreatedAfter and UpdatedAfter filters.
2. Create new Users
Send POST /api/customers/users. The response is the new User's ID, for example {"id": "users/123456-A"}. Store it, or send your own ID as externalId so you can find the User later.
Field | What to send |
| Required. The email must be unique across all of Mobaro, not just your organization. |
|
|
| Required when |
| Your system's ID for the User (External ID). |
|
|
| Exactly 4 digits (PIN Code). |
Other |
|
3. Update changed details
Send PUT /api/customers/users/{id}, again with the ID, External ID or email. Only the fields you send change. Update also accepts lockedProfile (Only allow administrator to make changes) and disableMobaroAuthentication (Disable Mobaro authentication). Sending a new email changes the User's sign-in email. Super Users, and Users who also belong to another Mobaro organization, can't be updated with a key: you get 401 Unauthorized.
⚠️ Heads-up: User create, update and delete requests share a limit of 2 requests per second across every API key, not just yours. Send them one at a time and retry after 429 Too Many Requests. See Handling errors, rate limits, and retry logic.
4. Disable leavers
Send PUT with isDisabled: true. The User can't sign in, but their history, Results and Certifications stay. Send false to enable them again. See How to deactivate a User.
🛑 Critical: DELETE /api/customers/users/{id} removes the User from your organization, and deletes their account if they're in no other organization. Their Certifications are deleted too, and it can't be undone. Super Users can't be deleted this way. Disable leavers unless you're sure. See Visibility and retention of certifications.
Manage User Groups
POST /api/customers/usergroups needs a name. You can also send externalId, description, users, administrators, delegateableUserGroups, locations, locationGroups, requireSSO and assignability (for example {"assignments": true}, the default). requireSSO is rejected unless your organization has single sign-on. Get a group by its ID or its External ID.
To change members there are two ways:
Replace the list:
PUT /api/customers/usergroups/{id}withusers,administratorsordelegateableUserGroups. The list you send becomes the whole list.Add or remove (Beta):
POST /api/customers/usergroups/{id}/relationswith, for example,{"users": {"add": ["users/123-A"], "remove": ["users/456-B"]}}. Everyone else stays.
⚠️ Heads-up: Sending one User in users with PUT removes every other member, and with them the Schedules, Assignments, Locations and Roles they had through the group. Use the relations endpoint for single joiners and leavers.
Deleting a group removes it from Schedules, Assignments, Locations and Location Groups, so its members lose what they had through it. For what groups do, see Create and manage User Groups.
Manage Roles
GET /api/customers/roles returns each Role's name, description, users and userGroups. PUT /api/customers/roles/{id} changes those four; users and userGroups replace the whole list. You can't create Roles or see their permissions through the API: set them up in the Backend, see Set up Roles to manage permissions. Deleting a Role takes its permissions away from everyone who had it.
Best practices
Set an External ID on every User and group your system manages, and look records up by it.
Give Roles to User Groups, not to individual Users, so your sync only has to maintain group membership.
Disable leavers rather than deleting them.
Only send fields that come from your system. Anything you send overwrites edits made in the Backend at the next sync.
Use a dedicated key for the sync, and pace User writes to stay under the shared limit.
Frequently asked questions
Why do I get 401 Unauthorized when I update some Users?
The key isn't allowed to change that User. Either the ID, External ID or email matches no User in your organization (look it up with GET first), or the User is a Super User or also belongs to another Mobaro organization. Contact Mobaro Support for those.
Can we import users in bulk?
Yes. Your integration can create them one at a time with POST /api/customers/users, within the 2-per-second limit. Mobaro can also import Users from an Excel sheet for you. See Create new users in your organization.
Some of our people already have a Mobaro account. Can the API add them?
No. Emails are unique across Mobaro, so creating a User whose email is used in another organization fails with 400 Bad Request. Contact Mobaro Support to add existing accounts to your organization.
Can I change users' notification settings through the API?
No. The Users endpoint doesn't accept notification settings. Change them in the Backend by editing the User and ticking Personalize settings, or each User changes their own in their profile.
How do I put new users into User Groups?
Add them to the group: POST /api/customers/usergroups/{id}/relations with their IDs under users.add, or send the full member list with PUT. The Users endpoint can't set groups.