v2

latestOpenAPI 3.1.02026-07-31515292.8 KB

Create Patient Call

post/api/v0/patient-calls/call

Headers

Idempotency-Keystring

Request body

type'PATIENT_OUTREACH'

An enumeration.

patient_namestring required

Name of the patient to call

patient_phonestring required

Phone number to dial. E.164 format preferred (e.g. +14155552671).

desired_call_tsstring date-time

When to place the call, as an ISO 8601 timestamp. If omitted, the call is scheduled to start within the next 5 minutes.

call_script_idstring required

ID of a call script belonging to your team. Create and manage scripts in the dashboard under Call Scripts. The script defines the questions asked when the patient answers live.

voice'KRISPIN' | 'RONALD' | 'PRIYA' | 'DEVANSH' required

Curated Cartesia voices available for patient calls.

Friendly names map to internal Cartesia voice IDs when dialing is activated.

external_idstring

Optional identifier you define for tracking (e.g. provider or campaign id).

metadataobject

Key/value pairs available to the agent while it runs the call script during the live call (e.g. medication name, appointment time). Also returned on the call response and webhooks.

leave_voicemail_if_no_answerboolean

If true, leave a voicemail when the patient does not answer. Voicemail is a fallback for unanswered calls, not a separate product.

voicemail_scriptstring

Message to leave if leave_voicemail_if_no_answer is true. Required when leave_voicemail_if_no_answer is true once the API is activated.

Example request

{
  "patient_name": "Alex Martin",
  "patient_phone": "+14155552671",
  "desired_call_ts": "2024-03-19T14:30:00Z",
  "call_script_id": "script_abc123",
  "external_id": "provider_123",
  "metadata": {
    "medication": "Atorvastatin",
    "appointment_date": "04-01-2024"
  },
  "voicemail_script": "Hi, this is Riverside Family Medicine calling about your prescription refill. Please call us back at 555-0100."
}

Response

Successful Response

successboolean required

call_idstring

already_existedboolean