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"
    }
  ]
}

List Call Audit Logs

Retrieve a paginated list of audit log entries for a specific call. Audit logs track create, update, and read events via PaperTrail, providing a full history of changes and access.


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

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the organization user that owns the call
`call_id`	integer	path	Yes	ID of the call
`event`	string	query	No	Filter by event type: `create`, `update`, or `read`
`from`	string	query	No	Start date filter (YYYY-MM-DD). Returns logs from the beginning of this day
`to`	string	query	No	End date filter (YYYY-MM-DD). Returns logs through the end of this day
`page`	integer	query	No	Page number (default: 1)
`per_page`	integer	query	No	Items per page (default: 25)

Example Request


curl -X GET "https://api.kismethealth.com/api/external/organization_users/123/calls/456/audit_logs?event=update&from=2025-01-01&to=2025-06-30&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


{
  "audit_logs": [
    {
      "id": 42,
      "event": "update",
      "user_id": "1",
      "object_changes": {
        "state": ["active", "ended"],
        "is_ended": [false, true],
        "updated_at": ["2025-07-16T14:00:00Z", "2025-07-16T14:30:00Z"]
      },
      "created_at": "2025-07-16T14:30:00Z"
    },
    {
      "id": 41,
      "event": "create",
      "user_id": "1",
      "object_changes": {
        "name": [null, "Initial Consult"],
        "state": [null, "active"]
      },
      "created_at": "2025-07-16T14:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 1,
    "total_count": 2
  }
}

Audit Log Properties

Property	Type	Description
`id`	integer	Unique identifier for the audit log entry
`event`	string	Type of event: `create`, `update`, or `read`
`user_id`	integer	ID of the user who triggered the event
`object_changes`	object \| null	Field changes as `{ "field": [old_value, new_value] }` pairs. `null` for `read` events
`created_at`	string	ISO 8601 timestamp of when the event was recorded

Event Types

create — Logged when the call is first created. object_changes contains initial field values as [null, value] pairs.
update — Logged when call fields are modified. object_changes contains [old_value, new_value] pairs for each changed field.
read — Logged when the call is accessed. object_changes is null.

Important Notes

Results are ordered by created_at descending (most recent first)
Date range filters are inclusive — from starts at beginning of day, to ends at end of day
The event filter accepts a single event type per request

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.