Users

Reading returns only registered users — those who have accepted an invite. Pending invitations and deactivated accounts are not returned.

Creating and deleting mirror the CMS user management: users are created as regular employees and optionally invited to the app, and only manually created users can be deleted. Profile pictures can be set for any employee, for example from an HR system that holds the photos.

Required scope: read:users for reading, write:users for creating, deleting and setting profile pictures.

Endpoints

List users

curl "https://customer.monotree.com/api/open/v1/users?group_id=1&per_page=25" \
  -H "Authorization: Bearer mono_your_token_here"

Response

{
  "data": {
    "id": 42,
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Head of Engineering",
    "email": "john@example.com",
    "type": "default",
    "avatar_url": "https://images.monotree.com/avatars/john-doe.jpg",
    "is_manager": false,
    "groups": [
      { "id": 1, "name": "Kitchen Staff", "type": "department", "is_manager": false, "created_at": "2026-01-15T10:00:00+00:00" }
    ],
    "hired_at": "2025-06-01",
    "date_of_birth": "1994-08-12",
    "is_away": false,
    "last_active_on": "2026-03-22T14:05:12.000000Z",
    "registered_at": "2025-06-01T09:00:00+00:00",
    "created_at": "2025-06-01T09:00:00+00:00"
  }
}

Field notes

• hired_at is the effective hire date: a manual override set in the CMS wins over the synced value.
• date_of_birth is null unless the customer collects it (e.g. via an onboarding field).
• title is the employee's job title, set per user in the CMS. It is null unless the customer fills it in, and nothing syncs it from the HR system. The profession group(s) remain the synced position: filter groups[] by type profession. Departments (type department) are the organizational/location unit; a user can belong to several.
• avatar_url is a direct URL to the profile picture, or null. Embedded user objects on posts, comments and announcements carry the same field.
• is_manager (top level) is true when the user manages at least one group. The is_manager flag on each groups[] entry tells which ones. To resolve an employee's manager(s), fetch the managers of their department group(s) via Groups.

Create a user

curl -X POST https://customer.monotree.com/api/open/v1/users \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "12345678",
    "phone_country_code": "NO",
    "groups": [1],
    "hired_at": "2026-09-01",
    "send_invite": true
  }'

Returns 201 with the same user object as GET /users/{id}, with registered_at null. A new user only shows up in GET /users after accepting the invite — keep the id from the create response if you need to delete the user before that.

• An email already used by an active user is rejected with 422 (errors.email).
• An email belonging to a deleted user restores that account instead of creating a duplicate: the fields you send are written over it, the response is still 201 and carries the existing id.
• Users are always created as regular employees (type: default) — bots have their own endpoints.

Delete a user

curl -X DELETE https://customer.monotree.com/api/open/v1/users/42 \
  -H "Authorization: Bearer mono_your_token_here"

Soft deletes the user, same as deleting in the CMS: they lose access and disappear from the app; creating a user with the same email later restores the account. Returns 204.

Only manually created users can be deleted — a user synced from an external system (HR or rota portal) belongs to that sync and returns 422. Bots, system accounts and already deleted users return 404.

Set a profile picture

curl -X POST https://customer.monotree.com/api/open/v1/users/42/avatar \
  -H "Authorization: Bearer mono_your_token_here" \
  -F "media=@./jane.jpg"

Send the image as a multipart/form-data field named media (jpg, png, gif, webp, bmp or svg, the same rule as the app's own upload). Returns 200 with the user object; avatar_url already points at the new picture.

• Works for any employee, including invited-but-unregistered and deactivated users. Bots return 404, set theirs with PUT /bots/{id}.
• Replaces whatever picture the user has, including one they chose themselves, and deletes the previous file. Colleagues are not notified.