Waiting Rooms

The Waiting Rooms API allows you to manage waiting rooms in your organization, including creating, listing, viewing, updating, and retiring waiting rooms.

Waiting Room Properties

Property	Type	Description
`id`	integer	Unique identifier for the waiting room
`organization_id`	integer	ID of the organization that owns the room (`null` for personal rooms)
`user_id`	integer	ID of the user who owns the room (`null` for organization rooms)
`name`	string	Human-readable name for the waiting room. This is the value you set when creating or updating a room.
`slug`	string	Read-only URL slug. Auto-generated from `name`, namespaced to your organization to keep it unique, and regenerated whenever `name` changes.
`theme`	string	Theme applied to the waiting room
`is_active`	boolean	Whether the waiting room is currently active
`created_at`	string	ISO 8601 timestamp of when the waiting room was created
`updated_at`	string	ISO 8601 timestamp of when the waiting room was last updated
`waiting_count`	integer	Number of participants currently waiting in the room
`user`	object	Owner information object
`user.display_name`	string	Display name of the owner — the user for personal rooms, or the organization name for organization rooms

name vs slug: You set name; slug is derived from it automatically and is read-only — you cannot set or change it directly. Rename a room by changing its name and the slug follows. Because the slug is the room’s URL, renaming changes that URL, so previously shared links will stop resolving.

Endpoints

List Waiting Rooms

Retrieve a paginated list of all waiting rooms in your organization.


GET /api/external/waiting_rooms

Parameters

Parameter	Type	Location	Required	Description
`page`	integer	query	No	Page number for pagination (default: 1)
`per_page`	integer	query	No	Number of results per page (default: 25)

Example Request


curl -X GET "https://api.kismethealth.com/api/external/waiting_rooms?page=1&per_page=5" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "waiting_rooms": [
    {
      "id": 1,
      "user_id": 101,
      "organization_id": null,
      "name": "Dr. Sarah Smith",
      "slug": "acme-healthcare-dr-sarah-smith",
      "theme": "ocean",
      "is_active": true,
      "created_at": "2025-07-16T14:00:00Z",
      "updated_at": "2025-07-16T14:05:00Z",
      "waiting_count": 3,
      "user": {
        "display_name": "Dr. Sarah Smith"
      }
    },
    {
      "id": 2,
      "user_id": null,
      "organization_id": 123,
      "name": "Front Desk",
      "slug": "acme-healthcare-front-desk",
      "theme": "forest",
      "is_active": true,
      "created_at": "2025-07-16T13:30:00Z",
      "updated_at": "2025-07-16T13:45:00Z",
      "waiting_count": 0,
      "user": {
        "display_name": "Acme Healthcare"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 5,
    "total_pages": 2,
    "total_count": 7
  }
}

Get Waiting Room Details

Retrieve detailed information about a specific waiting room.


GET /api/external/waiting_rooms/{slug}

Parameters

Parameter	Type	Location	Required	Description
`slug`	string	path	Yes	Slug of the waiting room

Example Request


curl -X GET "https://api.kismethealth.com/api/external/waiting_rooms/acme-healthcare-front-desk" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "id": 2,
  "user_id": null,
  "organization_id": 123,
  "name": "Front Desk",
  "slug": "acme-healthcare-front-desk",
  "theme": "forest",
  "is_active": true,
  "created_at": "2025-07-16T13:30:00Z",
  "updated_at": "2025-07-16T13:45:00Z",
  "waiting_count": 0,
  "user": {
    "display_name": "Acme Healthcare"
  }
}

Error Responses

404 Not Found: Returned when the waiting room slug does not exist or is not accessible to the authenticated client.

Create Waiting Room

Create a new organization-owned waiting room. Personal (provider) waiting rooms are provisioned automatically and aren’t created through this endpoint — create always produces a room owned by your organization.


POST /api/external/waiting_rooms

Parameters

Parameter	Type	Location	Required	Description
`waiting_room`	object	body	Yes	Waiting room details object
`waiting_room.name`	string	body	Yes	Human-readable name for the room. The `slug` is auto-generated from this.
`waiting_room.theme`	string	body	No	Theme to apply to the waiting room
`waiting_room.is_active`	boolean	body	No	Whether the waiting room is active (default: false)

slug cannot be set — it is generated from name.

Example Request


curl -X POST "https://api.kismethealth.com/api/external/waiting_rooms" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "waiting_room": {
      "name": "Front Desk",
      "theme": "default",
      "is_active": true
    }
  }'

Example Response


{
  "id": 3,
  "user_id": null,
  "organization_id": 123,
  "name": "Front Desk",
  "slug": "acme-healthcare-front-desk",
  "theme": "default",
  "is_active": true,
  "created_at": "2025-10-08T16:30:00Z",
  "updated_at": "2025-10-08T16:30:00Z",
  "waiting_count": 0,
  "user": {
    "display_name": "Acme Healthcare"
  }
}

Error Responses

422 Unprocessable Entity: Returned when validation fails (e.g., name is blank).

Update Waiting Room

Update an existing waiting room’s settings. Renaming a room (changing name) regenerates its slug, which changes the room’s URL — previously shared links will stop resolving.


PUT /api/external/waiting_rooms/{slug}

Parameters

Parameter	Type	Location	Required	Description
`slug`	string	path	Yes	Current slug of the waiting room
`waiting_room`	object	body	Yes	Waiting room details object
`waiting_room.name`	string	body	No	New name for the room. Regenerates the `slug`.
`waiting_room.theme`	string	body	No	Theme to apply to the waiting room
`waiting_room.is_active`	boolean	body	No	Whether the waiting room is active

slug cannot be set directly — change name to regenerate it.

Example Request


curl -X PUT "https://api.kismethealth.com/api/external/waiting_rooms/acme-healthcare-front-desk" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "waiting_room": {
      "name": "Reception",
      "is_active": false
    }
  }'

Example Response


{
  "id": 3,
  "user_id": null,
  "organization_id": 123,
  "name": "Reception",
  "slug": "acme-healthcare-reception",
  "theme": "default",
  "is_active": false,
  "created_at": "2025-10-08T16:30:00Z",
  "updated_at": "2025-10-08T16:45:00Z",
  "waiting_count": 0,
  "user": {
    "display_name": "Acme Healthcare"
  }
}

Error Responses

404 Not Found: Returned when the waiting room slug does not exist or is not accessible.
422 Unprocessable Entity: Returned when validation fails (e.g., name is blank).

Retire Waiting Room

Retire (soft-delete) an organization-owned waiting room. The room is removed from listings and can no longer be accessed or joined, but its record is retained for auditing. This cannot be undone through the API.


DELETE /api/external/waiting_rooms/{slug}

Parameters

Parameter	Type	Location	Required	Description
`slug`	string	path	Yes	Slug of the waiting room to retire

Example Request


curl -X DELETE "https://api.kismethealth.com/api/external/waiting_rooms/acme-healthcare-front-desk" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Response

204 No Content: The room was retired successfully.

Error Responses

404 Not Found: Returned when the waiting room slug does not exist or is not accessible.
422 Unprocessable Entity: Returned when the room cannot be retired — either it is currently in use (has active participants or an ongoing call) or it is a personal (provider) room, which cannot be retired.