Calls API

Manage outbound phone calls with AI agents. All calls are initiated asynchronously and can be monitored via status polling.

Create Calls

Initiate new outbound calls to patients.

POST /api/v1/calls

Purpose

Creates outbound calls to patients using a specified AI agent. The system will automatically retrieve the patient's phone number from their record.

Request Body

{
  "patients": [               // Required: Array of patient objects
    {
      "patientId": "22222222-2222-2222-2222-222222222222",   // Required: Patient UUID v4
      "extended": {}         // Optional: Per-patient custom metadata object
    }
  ],
  "agentId": "22222222-2222-2222-2222-222222222222",         // Required: AI Agent configuration UUID
  "recording": true,         // Optional: Enable call recording (default: true)
  "reason": "string",        // Optional: Reason for the call
  "name": "string",          // Optional: Name for the batch
  "scheduledAt": "string",    // Optional: ISO 8601 date string for scheduled calls
  "description": "string"     // Optional: Description for scheduled calls
}

Response

{
  "success": true,
  "batchId": "22222222-2222-2222-2222-222222222222",         // Batch ID for tracking
  "totalQueued": 0,           // Number of calls queued
  "totalInitiated": 1,        // Number of calls immediately initiated
  "calls": [
    {
      "callId": "22222222-2222-2222-2222-222222222222",
      "roomName": "outbound-[callId]",
      "status": "initiating"   // or "queued" in production mode
    }
  ],
  "message": "Batch created and initiated 1 calls",
  "payload": {
    // Echo of the request payload
  }
}

Initial Status Values

The create call response will have one of these statuses:

queued: Call is waiting in queue due to high traffic (production mode)
initiating: Call is being immediately processed (demo mode or low traffic)

Multiple Patients

To create calls for multiple patients, include multiple patient objects in the patients array:

{
  "patients": [
    {
      "patientId": "11111111-1111-1111-1111-111111111111",
      "extended": { 
        "appointment": {
          "name": "General Check Up",
          "start_time": "August 22, 2025 at 10:30 AM"
        } 
      }
    },
    {
      "patientId": "22222222-2222-2222-2222-222222222222",
      "extended": { 
        "appointment": {
          "name": "Follow-up Visit",
          "start_time": "August 23, 2025 at 2:30 PM"
        } 
      }
    }
  ],
  "agentId": "12121212-1212-1212-1212-121212121212",
  "recording": true
}

Notes

All calls use the same agent configuration
Each patient can have their own extended metadata
Each call gets its own unique call ID
Calls are processed in parallel when possible
Phone numbers are automatically fetched from patient records
Returns 400 if any patient is missing a phone number
If scheduledAt is provided, the calls will be scheduled for later execution
Scheduled calls require a valid future date in ISO 8601 format

Example

curl -X POST https://orchestrator.helloblair.com/api/v1/calls \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patients": [{
      "patientId": "YOUR_PATIENT_ID"
    }],
    "agentId": "YOUR_AGENT_ID",
    "recording": true
  }'

Get Calls

Retrieve a paginated list of calls for your organization.

GET /api/v1/calls

Purpose

Lists all calls for your organization with pagination support and optional filtering by end date.

Query Parameters

Parameter	Type	Required	Description	Default	Range
`size`	integer	No	Number of results per page	100	1-500
`start`	integer	No	Starting index (1-based)	1	>= 1
`ended_after`	ISO 8601 string	No	Filter calls ended after this date	All calls	-

Response

{
  "data": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "status": "completed",
      "phone_number": "+15555551234",
      "direction": "outbound",
      "created_at": "2024-01-15T10:30:00.000Z",
      "started_at": "2024-01-15T10:30:15.000Z",
      "ended_at": "2024-01-15T10:35:45.000Z",
      "final_report": {
        // Content varies by agent configuration
      },         // JSONB field, nullable
      "batch_id": "22222222-2222-2222-2222-222222222222",        // Optional, present for batch calls
      "agent_id": "22222222-2222-2222-2222-222222222222",
      "duration": 330,           // Calculated from timestamps
      "patient": {               // null if no patient associated
        "patient_id": "22222222-2222-2222-2222-222222222222",
        "first_name": "John",
        "last_name": "Doe",
        "birth_date": "1990-01-01",
        "email": "john.doe@email.com",  // nullable
        "phone_number": "+15555551234"
      },
      "client_metadata": {       // nullable
        // Content varies by organization settings
      }
    }
  ],
  "pagination": {
    "start": 1,
    "requested_size": 100,
    "returned_count": 25,
    "total": 150,
    "hasMore": true,
    "ended_after": "2024-01-01T00:00:00.000Z"
  }
}

Response Fields

duration: Calculated duration in seconds (null if call hasn't ended)
patient: Embedded patient object with details (null if patient not found)
final_report: JSONB field with agent-specific data (nullable)
batch_id: ID of the batch/campaign if call was part of a batch (null for single calls)
pagination.start: The 1-based index you requested
pagination.requested_size: The size you requested
pagination.returned_count: Actual number of records returned
pagination.total: Total records matching the filter
pagination.hasMore: Whether more pages are available

Example

# Get first page with default size
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls" \
  -H "X-API-Key: YOUR_API_KEY"

# Get second page with custom size
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls?size=50&start=51" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter by end date
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls?ended_after=2024-01-01T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

Get Call

Retrieve detailed information about a specific call.

GET /api/v1/calls/{callId}

Purpose

Get comprehensive details about a specific call including timing, patient information, and the final agent report.

Path Parameters

Parameter	Type	Description
`callId`	uuid	The unique identifier of the call

Response

{
  "id": "22222222-2222-2222-2222-222222222222",
  "status": "completed",
  "phone_number": "+15555551234",
  "direction": "outbound",
  "created_at": "2024-01-15T10:30:00.000Z",
  "started_at": "2024-01-15T10:30:15.000Z",
  "ended_at": "2024-01-15T10:35:45.000Z",
  "final_report": {         // JSONB field, nullable
    // Content varies by agent configuration
  },
  "batch_id": "22222222-2222-2222-2222-222222222222",         // Optional, present for batch calls
  "agent_id": "22222222-2222-2222-2222-222222222222",
  "duration": 330,           // Calculated from timestamps
  "patient": {               // null if no patient associated
    "patient_id": "22222222-2222-2222-2222-222222222222",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-01-01",
    "email": "john.doe@email.com",  // nullable
    "phone_number": "+15555551234"
  },
  "client_metadata": {       // nullable
    // Content varies by organization settings
  }
}

Response Fields

duration: Calculated duration in seconds (null if call hasn't ended)
patient: Full patient details (null if patient not found)
final_report: JSONB field with agent-specific data (nullable)
batch_id: ID of the batch/campaign if call was part of a batch (null for single calls)

Example

curl -X GET https://orchestrator.helloblair.com/api/v1/calls/YOUR_CALL_ID \
  -H "X-API-Key: YOUR_API_KEY"

Get Campaigns

Retrieve a list of call campaigns (batch logs) for your organization.

GET /api/v1/calls/campaigns

Purpose

Lists all call campaigns (batches) created for your organization with pagination support.

Query Parameters

Parameter	Type	Required	Description	Default	Range
`size`	integer	No	Number of results per page	100	1-500
`start`	integer	No	Starting index (1-based)	1	>= 1

Response

{
  "data": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Appointment Reminders Campaign",  // nullable
      "agent_id": "22222222-2222-2222-2222-222222222222",
      "created_at": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "start": 1,
    "requested_size": 100,
    "returned_count": 10,
    "total": 25,
    "hasMore": true
  }
}

Notes

Campaigns are batch call operations created when multiple calls are initiated together

Example

curl -X GET "https://orchestrator.helloblair.com/api/v1/calls/campaigns?size=20&start=1" \
  -H "X-API-Key: YOUR_API_KEY"

Get Campaign Calls

Retrieve all calls for a specific campaign.

GET /api/v1/calls/campaigns/{batchId}

Purpose

Get all calls associated with a specific campaign (batch), including campaign details.

Path Parameters

Parameter	Type	Description
`batchId`	uuid	The unique identifier of the campaign/batch

Query Parameters

Parameter	Type	Required	Description	Default	Range
`size`	integer	No	Number of results per page	100	1-500
`start`	integer	No	Starting index (1-based)	1	>= 1
`ended_after`	ISO 8601 string	No	Filter calls ended after this date	All calls	-

Response

{
  "campaign": {
    "id": "22222222-2222-2222-2222-222222222222",
    "name": "Appointment Reminders Campaign",  // nullable
    "agentId": "22222222-2222-2222-2222-222222222222",
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  "data": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "status": "completed",
      "phone_number": "+15555551234",
      "direction": "outbound",
      "created_at": "2024-01-15T10:30:00.000Z",
      "started_at": "2024-01-15T10:30:15.000Z",
      "ended_at": "2024-01-15T10:35:45.000Z",
      "final_report": {
        // Content varies by agent configuration
      },
      "agent_id": "22222222-2222-2222-2222-222222222222",
      "duration": 330,           // Calculated from timestamps
      "patient": {               // null if no patient associated
        "patient_id": "22222222-2222-2222-2222-222222222222",
        "first_name": "John",
        "last_name": "Doe",
        "birth_date": "1990-01-01",
        "email": "john.doe@email.com",  // nullable
        "phone_number": "+15555551234"
      },
      "client_metadata": {       // nullable
        // Content varies by organization settings
      }
    }
  ],
  "pagination": {
    "start": 1,
    "requested_size": 100,
    "returned_count": 25,
    "total": 50,
    "hasMore": true,
    "ended_after": "2024-01-01T00:00:00.000Z"
  }
}

Notes

Returns 404 if campaign doesn't exist or doesn't belong to your organization
Response includes full patient details for each call
Uses same pagination structure as other list endpoints

Example

# Get first page with default size
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls/campaigns/YOUR_BATCH_ID" \
  -H "X-API-Key: YOUR_API_KEY"

# Get second page with custom size
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls/campaigns/YOUR_BATCH_ID?size=50&start=51" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter by end date
curl -X GET "https://orchestrator.helloblair.com/api/v1/calls/campaigns/YOUR_BATCH_ID?ended_after=2024-01-01T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

Hangup Call

Terminate an ongoing call immediately.

DELETE /api/v1/calls/{callId}

Purpose

Forcefully end an active call. This is useful for emergency situations or when a call needs to be terminated before natural completion.

Path Parameters

Parameter	Type	Description
`callId`	uuid	The unique identifier of the call to terminate

Response

Success response when call is terminated:

{
  "callId": "22222222-2222-2222-2222-222222222222",
  "message": "Call terminated successfully"
}

Error Response

When call cannot be terminated (wrong status or not found):

{
  "success": false,
  "error": {
    "status": 400,
    "message": "Call was not in a status that could be hung up",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_1234567890_abc123",
    "path": "/api/v1/calls/uuid",
    "method": "DELETE"
  }
}

Allowed Statuses for Termination

initiating: Call is being set up
dialing: Call is ringing
in-progress: Call is active

Error Messages

400 Bad Request: "There are no ongoing calls with that call ID" - Call not found or doesn't belong to your organization
400 Bad Request: "Call was not in a status that could be hung up" - Call is not in initiating, dialing, or in-progress status

Notes

The call will be marked as failed after termination
Only calls in initiating, dialing, or in-progress status can be terminated

Example

curl -X DELETE https://orchestrator.helloblair.com/api/v1/calls/YOUR_CALL_ID \
  -H "X-API-Key: YOUR_API_KEY"

Call Lifecycle

After creation, a call progresses through these statuses:

queued → Call is waiting in queue (production mode with high traffic)
initiating → System is preparing the call
dialing → Calling the recipient
in-progress → Call is active and conversation is happening
summarizing → Call has ended and the AI is generating the final report
completed → Call ended normally with final report ready
failed → Call failed at any stage

Call Direction

outbound: Calls initiated by the system
inbound: Calls received by the system

Note: When you create a call, it starts in either queued or initiating status. The other statuses are seen when retrieving the call details through GET /api/v1/calls/{callId}.

Best Practices

Always check patient phone numbers before initiating calls
Use the patients array for both single and multiple calls
Store call IDs for tracking and reporting
Handle queued status appropriately in your UI
Use 1-based pagination - start index begins at 1, not 0
Monitor campaign performance using the campaigns endpoints

Validation Error Details

When patient validation fails, the API returns structured error information:

{
  "statusCode": 400,
  "message": "Validation failed for one or more patients",
  "errors": [
    {
      "index": 0,
      "patientId": "22-2222-2222-2222-22-222222-2222",
      "failedObject": { ... },
      "errors": [
        {
          "field": "patientId",
          "message": "patientId must be a valid UUID",
          "expectedFormat": "UUID v4 (e.g., \"22222222-2222-2222-2222-222222222222\")",
          "receivedValue": "22-2222-2222-2222-22-222222-2222"
        }
      ]
    }
  ]
}

Common Error Scenarios

Missing Phone Numbers: Returns 400 with list of patient IDs missing phone numbers
Invalid Patient ID: Returns validation error with expected UUID v4 format
Invalid Extended Object: Returns validation error if extended is not an object

Create Calls​

Purpose​

Request Body​

Response​

Initial Status Values​

Multiple Patients​

Notes​

Example​

Get Calls​

Purpose​

Query Parameters​

Response​

Response Fields​

Example​

Get Call​

Purpose​

Path Parameters​

Response​

Response Fields​

Example​

Get Campaigns​

Purpose​

Query Parameters​

Response​

Notes​

Example​

Get Campaign Calls​

Purpose​

Path Parameters​

Query Parameters​

Response​

Notes​

Example​

Hangup Call​

Purpose​

Path Parameters​

Response​

Error Response​

Allowed Statuses for Termination​

Error Messages​

Notes​

Example​

Call Lifecycle​

Call Direction​

Best Practices​

Validation Error Details​

Common Error Scenarios​

Create Calls

Purpose

Request Body

Response

Initial Status Values

Multiple Patients

Notes

Example

Get Calls

Purpose

Query Parameters

Response

Response Fields

Example

Get Call

Purpose

Path Parameters

Response

Response Fields

Example

Get Campaigns

Purpose

Query Parameters

Response

Notes

Example

Get Campaign Calls

Purpose

Path Parameters

Query Parameters

Response

Notes

Example

Hangup Call

Purpose

Path Parameters

Response

Error Response

Allowed Statuses for Termination

Error Messages

Notes

Example

Call Lifecycle

Call Direction

Best Practices

Validation Error Details

Common Error Scenarios