Calls

The Calls API allows you to retrieve and manage call data for users in your organization.

Endpoints

List Calls

Retrieve a paginated list of calls for a specific organization user.


GET /api/external/organization_users/{organization_user_id}/calls

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the user whose calls to list
`page`	integer	query	No	Page number
`per_page`	integer	query	No	Items per page

Example Request


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

Example Response


{
  "calls": [
    {
      "id": 1,
      "name": "Initial Consult",
      "livekit_session_id": "lk-session-xyz",
      "state": "active",
      "has_egresses": false,
      "is_recording": true,
      "is_canvas_locked": false,
      "is_ended": false,
      "created_at": "2025-07-16T14:00:00Z",
      "updated_at": "2025-07-16T14:05:00Z",
      "participants": [
        {
          "id": 1,
          "participant_type": "Recipient",
          "name": "Dave"
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 1
  }
}

Get Call Details

Retrieve detailed information about a specific call.


GET /api/external/organization_users/{organization_user_id}/calls/{id}

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the organization user that owns the call
`id`	string	path	Yes	ID of the call to retrieve

Example Request


curl -X GET "https://api.kismethealth.com/api/external/organization_users/123/calls/456" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "id": 123,
  "name": "Initial Consult",
  "livekit_session_id": "lk-session-xyz",
  "state": "active",
  "has_egresses": false,
  "is_recording": true,
  "is_canvas_locked": false,
  "is_ended": false,
  "created_at": "2025-07-16T14:00:00Z",
  "updated_at": "2025-07-16T14:05:00Z",
  "participants": [
    {
      "id": 1,
      "participant_type": "Recipient",
      "name": "Dave"
    }
  ]
}

Call Properties

Core Properties

Property	Type	Description
`id`	integer	Unique identifier for the call
`name`	string	Display name for the call
`livekit_session_id`	string	LiveKit session identifier
`state`	string	Current state of the call
`created_at`	string	ISO 8601 timestamp of when the call was created
`updated_at`	string	ISO 8601 timestamp of when the call was last updated

Status Properties

Property	Type	Description
`has_egresses`	boolean	Whether the call has egresses (a recording)
`is_recording`	boolean	Whether the call is being recorded
`is_canvas_locked`	boolean	Whether the canvas is locked
`is_ended`	boolean	Whether the call has ended

Participants

Each call includes an array of participants with the following properties:

Property	Type	Description
`id`	integer	Unique identifier for the participant
`participant_type`	string	Type of participant (e.g., “Recipient” or “User”)
`name`	string	Display name of the participant

Code Examples

TypeScript/Node.js


const getCallsForUser = async (userId: number, page: number = 1, perPage: number = 25) => {
  const response = await fetch(
    `https://api.kismethealth.com/api/external/organization_users/${userId}/calls?page=${page}&per_page=${perPage}`,
    {
      headers: {
        'X-Client-ID': process.env.KISMET_CLIENT_ID,
        'X-Client-Secret': process.env.KISMET_CLIENT_SECRET,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
};
 
const getCallDetails = async (userId: number, callId: number) => {
  const response = await fetch(
    `https://api.kismethealth.com/api/external/organization_users/${userId}/calls/${callId}`,
    {
      headers: {
        'X-Client-ID': process.env.KISMET_CLIENT_ID,
        'X-Client-Secret': process.env.KISMET_CLIENT_SECRET,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
};

Python


import requests
 
def get_calls_for_user(user_id, page=1, per_page=25):
    response = requests.get(
        f'https://api.kismethealth.com/api/external/organization_users/{user_id}/calls',
        headers={
            'X-Client-ID': 'your-client-id',
            'X-Client-Secret': 'your-client-secret',
            'Content-Type': 'application/json'
        },
        params={
            'page': page,
            'per_page': per_page
        }
    )
    
    response.raise_for_status()
    return response.json()
 
def get_call_details(user_id, call_id):
    response = requests.get(
        f'https://api.kismethealth.com/api/external/organization_users/{user_id}/calls/{call_id}',
        headers={
            'X-Client-ID': 'your-client-id',
            'X-Client-Secret': 'your-client-secret',
            'Content-Type': 'application/json'
        }
    )
    
    response.raise_for_status()
    return response.json()

Error Handling

Common error responses:

404 Not Found


{
  "error": "Not Found",
}

401 Unauthorized


{
  "error": "Unauthorized",
}

Always handle these errors appropriately in your application code.