Roles

The Roles API lets you discover which roles you are permitted to assign — for example, when choosing the role_names for an invite.

Role Properties

Property	Type	Description
`id`	integer	Unique identifier for the role
`name`	string	Machine-readable role name (e.g. `provider`)
`description`	string	Human-readable description of the role

Endpoints

List Assignable Roles

Retrieve a paginated list of the roles the authenticated client is permitted to assign. The result is scoped to your permission level — you only see roles at or below your own. For example, an organization admin sees organization_admin, provider, and provider_assistant; a caller with no role-granting permission receives an empty list.


GET /api/external/roles

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/roles" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "roles": [
    {
      "id": 3,
      "name": "provider_assistant",
      "description": "Assists a provider and can join calls on their behalf"
    },
    {
      "id": 2,
      "name": "provider",
      "description": "Creates and runs calls and waiting rooms"
    },
    {
      "id": 1,
      "name": "organization_admin",
      "description": "Manages the organization, its members, and invites"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 3
  }
}