Management API — Users & Rooms

Native JSON API for reading users, managing room group mappings, and controlling room membership with full CRUD and sync operations.

Overview

The native Management API provides a JSON-first interface for reading users, managing room group mappings, and controlling room membership directly — without going through the SCIM abstraction layer. All endpoints use Bearer authentication and return JSON. The base URL is https://api.whoot.me.

Users

User endpoints require the api:users:read scope for read operations and api:users:write for mutations.

• GET /users — List all provisioned users in the organisation. Supports limit and offset query parameters for pagination.
• GET /users/{id} — Get a single user by their whoot. user id.
• PATCH /users/{id} — Update user profile attributes such as display name or active status.
• DELETE /users/{id} — Deactivate a user. This is a soft operation — the user record is retained.

// GET /users?limit=20&offset=0
// Response — 200 OK
{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "alice@acme.com",
      "display_name": "Alice Chen",
      "active": true,
      "created_at": "2026-01-15T09:00:00.000Z"
    }
  ],
  "total": 72,
  "limit": 20,
  "offset": 0
}

Rooms

Room endpoints give you visibility into your organisation's voice rooms and their SCIM group mappings. They require api:rooms:read for read operations and api:rooms:write for mutations.

• GET /rooms — List all rooms in the organisation.
• GET /rooms/{id} — Get a room by id, including its current SCIM group mapping if one exists.
• PATCH /rooms/{id} — Update the room's display name or external id within the associated group mapping.
• DELETE /rooms/{id} — Remove the SCIM group mapping for the room. The room itself is not deleted.

// GET /rooms/{id}
// Response — 200 OK
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "name": "Equities Desk",
  "display_name": "Equities Desk",
  "external_id": "okta-group-eq-001",
  "member_count": 12,
  "created_at": "2026-01-20T10:00:00.000Z"
}

Room Members

Member endpoints control who belongs to a room and whether they hold transmit permission. They require api:rooms:read for reads and api:rooms:write for mutations.

• GET /rooms/{id}/members — List all members of the room, including each member's transmit permission status.
• POST /rooms/{id}/members — Add a single user to the room. Include "tx_permission": true to grant transmit access (defaults to false).
• PUT /rooms/{id}/members — Replace the room's complete member list in one operation. Users present in the request are added or updated; users not in the request are removed. Use this for a full sync from your source of truth.
• DELETE /rooms/{id}/members/{userId} — Remove a specific user from the room.

// POST /rooms/{id}/members — add a member with transmit permission
{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tx_permission": true
}

// Response — 201 Created
{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "room_id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "tx_permission": true
}

// PUT /rooms/{id}/members — sync the full member list
{
  "members": [
    { "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tx_permission": true },
    { "user_id": "b2c3d4e5-f6a7-8901-bcde-f01234567891", "tx_permission": false },
    { "user_id": "c3d4e5f6-a7b8-9012-cdef-012345678902", "tx_permission": false }
  ]
}

// Response — 200 OK
{
  "room_id": "...",
  "members_added": 1,
  "members_updated": 1,
  "members_removed": 2
}