{"openapi":"3.1.0","info":{"title":"Hippocratic AI Agent API Suite","description":"The Hippocratic AI Agents are the first safety-focused generative AI healthcare agents for patient-facing non-diagnostic clinical tasks. Our API is designed to allow partners to take advantage of these agents in their own workflows.\n\nPartners send us information about patients, members, and other contacts, and specify the outreach they would like our agent to perform. The Hippocratic AI Agent performs the the outreach, and returns a summary and any structured data to the partner.","version":"1.0"},"paths":{"/api/v1/contacts":{"post":{"tags":["Partner API v1"],"summary":"Submit patient demographic and scheduling data","description":"Submit patient demographic and scheduling data.\n\n**Enhanced Functionality:**\nThis endpoint now supports combined payloads including:\n- Contact data (required)\n- Medications data (optional)\n- Outreach data (optional)\n- Related persons data (optional) — list of people associated with the patient (e.g., emergency contacts, caregivers)\n\nAll processing is synchronous - responses are returned immediately without waiting for pipeline processing.\n\n**Data Processing:**\nSubmitted patient data is fully processed and validated before a response is returned.\nIf any step of patient data processing fails, the contact will be marked as failed in the response.\n\n**Authentication:**\nThis endpoint supports dual authentication methods:\n- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication\n  - Header: `Authorization: Bearer <JWT_TOKEN>`\n  - Token must include `partner_id` claim\n  - Token is validated for signature, expiration, issuer, and audience\n\n- **Verification Token**: For partners using legacy authentication\n  - Header: `verification-token: <ENCRYPTED_TOKEN>`\n  - Token format: `partner_id:verification_token` (encrypted)\n  - Validated against partner credentials\n\nYour partner account is configured for one of these methods. Please use the authentication method assigned to your account.\nIf you attempt to use the wrong method, you will receive a 401 Unauthorized error.\n\n**Response Codes:**\n- `201 Created`: Successfully processed contact data (contact-only requests)\n- `200 OK`: Successfully processed combined payload (contact + medications/outreach)\n- `207 Multi-Status`: Partially successful (some contacts/medications/outreach failed)\n- `401 Unauthorized`: Authentication failed or wrong authentication method used\n- `400 Bad Request`: Invalid request payload\n- `500 Internal Server Error`: Server error during processing","operationId":"partner_contact_notification_api_v1_contacts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactsBundleRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/medications":{"post":{"tags":["Partner API v1"],"summary":"Submit medication data for multiple patients","description":"Submit medication data for multiple patients.\n\nUse this endpoint to submit a standalone medication list for patients already registered via `/contacts`.\nEach entry is matched by MRN. For submitting medications alongside a new or updated contact record,\nuse the `/contacts` endpoint with the `medications` field instead.\n\n**Authentication:**\nThis endpoint supports dual authentication methods:\n- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication\n  - Header: `Authorization: Bearer <JWT_TOKEN>`\n  - Token must include `partner_id` claim\n  - Token is validated for signature, expiration, issuer, and audience\n\n- **Verification Token**: For partners using legacy authentication\n  - Header: `verification-token: <ENCRYPTED_TOKEN>`\n  - Token format: `partner_id:verification_token` (encrypted)\n  - Validated against partner credentials\n\nYour partner account is configured for one of these methods. Please use the authentication method assigned to your account.\nIf you attempt to use the wrong method, you will receive a 401 Unauthorized error.\n\n**Response Codes:**\n- `201 Created`: Successfully processed medication data\n- `401 Unauthorized`: Authentication failed or wrong authentication method used\n- `400 Bad Request`: Invalid request payload\n- `500 Internal Server Error`: Server error during processing","operationId":"partner_medication_notification_api_v1_medications_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MedicationRequestBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/appointments":{"post":{"tags":["Partner API v1"],"summary":"Submit appointment scheduling data for a patient","description":"Submit appointment scheduling data for a patient.\n\nUse this endpoint to send upcoming, previous, or procedure-related appointment details\nfor a patient identified by MRN. The patient must already exist via a prior `/contacts` submission.\n\n**Authentication:**\nThis endpoint supports dual authentication methods:\n- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication\n  - Header: `Authorization: Bearer <JWT_TOKEN>`\n  - Token must include `partner_id` claim\n  - Token is validated for signature, expiration, issuer, and audience\n\n- **Verification Token**: For partners using legacy authentication\n  - Header: `verification-token: <ENCRYPTED_TOKEN>`\n  - Token format: `partner_id:verification_token` (encrypted)\n  - Validated against partner credentials\n\nYour partner account is configured for one of these methods. Please use the authentication method assigned to your account.\nIf you attempt to use the wrong method, you will receive a 401 Unauthorized error.\n\n**Response Codes:**\n- `201 Created`: Successfully processed appointment data\n- `401 Unauthorized`: Authentication failed or wrong authentication method used\n- `400 Bad Request`: Invalid request payload\n- `500 Internal Server Error`: Server error during processing","operationId":"partner_appointment_notification_api_v1_appointments_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/outreach/cancel":{"post":{"tags":["Outreach Management API"],"summary":"Cancel all outstanding outreaches for a patient","description":"Cancel all outstanding outreaches for a patient identified by external_contact_id.\n\n**Authentication:**\nThis endpoint supports dual authentication methods:\n- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication\n  - Header: `Authorization: Bearer <JWT_TOKEN>`\n  - Token must include `partner_id` claim\n  - Token is validated for signature, expiration, issuer, and audience\n\n- **Verification Token**: For partners using legacy authentication\n  - Header: `verification-token: <ENCRYPTED_TOKEN>`\n  - Token format: `partner_id:verification_token` (encrypted)\n  - Validated against partner credentials\n\nYour partner account is configured for one of these methods. Please use the authentication method assigned to your account.\nIf you attempt to use the wrong method, you will receive a 401 Unauthorized error.\n\n**Behavior:**\nAll active outreaches for the patient are cancelled in a single request.\nThe response includes the list of cancelled outreach IDs and their updated status.\n\n**Response Codes:**\n- `200 OK`: Successfully cancelled one or more outreaches\n- `404 Not Found`: Patient not found OR no outstanding outreaches found\n- `401 Unauthorized`: Authentication failed or wrong authentication method used\n- `500 Internal Server Error`: Server error during processing\n\n**Request Body:**\n```json\n{\n    \"external_contact_id\": \"MRN123456\",\n    \"reason\": \"Patient requested cancellation\"  // Optional\n}\n```\n\n**Success Response (200):**\n```json\n{\n    \"version\": \"1.0\",\n    \"status\": \"success\",\n    \"message\": \"Successfully cancelled 2 outreach(es)\",\n    \"cancelled_outreaches\": [\n        {\"outreach_id\": \"uuid-1\", \"status\": \"archived\"},\n        {\"outreach_id\": \"uuid-2\", \"status\": \"archived\"}\n    ],\n    \"patient_id\": \"patient-uuid\"\n}\n```\n\n**Error Response (404):**\n```json\n{\n    \"detail\": \"No outstanding outreaches found for patient\"\n}\n```","operationId":"cancel_outreach_api_v1_outreach_cancel_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachCancelRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachCancelResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/outreach/create":{"post":{"tags":["Outreach Management API"],"summary":"Create direct outreach for a campaign","description":"Create direct outreach for a campaign for a patient identified by contact_id (MRN).\n\n**Authentication:**\nThis endpoint supports dual authentication methods:\n- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication\n  - Header: `Authorization: Bearer <JWT_TOKEN>`\n  - Token must include `partner_id` claim\n  - Token is validated for signature, expiration, issuer, and audience\n\n- **Verification Token**: For partners using legacy authentication\n  - Header: `verification-token: <ENCRYPTED_TOKEN>`\n  - Token format: `partner_id:verification_token` (encrypted)\n  - Validated against partner credentials\n\nYour partner account is configured for one of these methods. Please use the authentication method assigned to your account.\nIf you attempt to use the wrong method, you will receive a 401 Unauthorized error.\n\n**Scheduling Rules:**\n- `scheduled_at`: Optional — defaults to now + 10 minutes. Must be at most 48 hours in the future and no more than 1 hour in the past.\n- `expires_at`: Optional — defaults to now + 48 hours. Must be at least 1 hour in the future and after `scheduled_at`.\n\n**Response Codes:**\n- `201 Created`: Successfully created outreach\n- `400 Bad Request`: Validation error (invalid datetime, expires before scheduled, etc.)\n- `404 Not Found`: Patient not found with the provided contact_id\n- `401 Unauthorized`: Authentication failed or wrong authentication method used\n- `500 Internal Server Error`: Server error during processing\n\n**Request Body:**\n```json\n{\n    \"contact_id\": \"MRN123456\",                    // Required: MRN\n    \"campaign_id\": \"campaign-uuid-789\",           // Required: Campaign UUID\n    \"scheduled_at\": \"2025-01-15T10:00:00Z\",      // Optional: ISO datetime (defaults to now + 10 min)\n    \"expires_at\": \"2025-01-17T10:00:00Z\",         // Optional: ISO datetime (defaults to now + 48 hours)\n    \"dry_run\": false                              // Optional: Test mode without creating outreach\n}\n```\n\n**Success Response (201):**\n```json\n{\n    \"status\": \"success\",\n    \"message\": \"Successfully created outreach for campaign\",\n    \"outreach_id\": \"outreach-uuid-123\"\n}\n```\n\n**Validation Error Response (400):**\n```json\n{\n    \"detail\": \"scheduled_at must be at least 1 hour in the past\"\n}\n```\n\n**Patient Not Found Response (404):**\n```json\n{\n    \"detail\": \"No patient found with contact_id: MRN123456\"\n}\n```","operationId":"create_outreach_api_v1_outreach_create_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutreachCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/tasks":{"post":{"tags":["Partner API v1"],"summary":"Submit outreach task bundles","description":"Submit a batch of outreach task bundles.\n\nEach item in the batch defines three things:\n- **`target`** — who the AI agent will contact (Patient, Practitioner, etc.)\n- **`focus`** — the reason for the outreach (Appointment, MedicationRequest, Encounter, etc.) — optional\n- **`task`** — when and how to run the outreach (timing, priority, classification)\n\nUp to **10 items** can be submitted per request. Each item is processed independently —\none failure does not cancel other items in the batch.\n\n---\n\n### `target` and `focus` — resource actions\n\nBoth `target` and `focus` use the same `TaskResource` shape with an explicit `action` field:\n\n```json\n{\n  \"resource_type\": \"Patient\",\n  \"action\": \"upsert\",\n  \"data\": { ... }\n}\n```\n\n**`action=\"upsert\"`** — HAI creates or updates the resource using the fields in `data`.\nUse this when sending a new or updated record. All required fields for the resource type must be present.\n\n**`action=\"reference\"`** — HAI looks up an existing resource by its lookup key only.\nUse this when the resource already exists and no update is needed.\n`data` must contain only the lookup key (e.g. `mrn` for Patient, `npi` for Practitioner).\nReturns `status=failed` for that item if the resource is not found.\n\n---\n\n### Required `data` fields per resource type\n\n| resource_type | action=upsert (required) | action=reference (lookup key) |\n|--------------|--------------------------|-------------------------------|\n| `Patient` | `mrn`, `first_name`, `last_name` | `mrn` |\n| `Practitioner` | `npi`, `provider_name` | `npi` |\n| `Appointment` | `appointment_id`, `start` | `appointment_id` |\n| `Encounter` | `encounter_id` | `encounter_id` |\n| `MedicationRequest` | `rx_number`, `medication_name` | `rx_number` |\n\nAdditional optional fields (e.g. `dob`, `phone`, `email`, `gender` for Patient;\n`provider_name` for Appointment) are accepted and stored when provided. GET Appointment\nreturns `provider_name` from the stored participant display.\n\n---\n\n### `task` fields\n\n| field | required | description |\n|-------|----------|-------------|\n| `external_id` | yes | Your unique identifier for this task. Submitting the same `external_id` again returns `status=duplicate` and **refreshes** the target/`for`/`focus` resources (re-upsert + SNOW sync) against the existing task — no new task is created. A transient SNOW failure during that refresh surfaces as `failed` (retryable with the same `external_id`), not `duplicate`. |\n| `task_tag` | yes | Classification / reason code (e.g. `pre_appointment_reminder`, `medication_adherence_followup`). |\n| `task_group` | no | Optional batch or campaign identifier for grouping tasks. |\n| `priority` | no | `routine` (default) \\| `urgent` \\| `asap` \\| `stat` |\n| `requested_start` | no | ISO 8601 UTC — earliest time to begin outreach. |\n| `requested_end` | no | ISO 8601 UTC — hard cutoff after which outreach will not be attempted. |\n| `timezone` | no | IANA timezone string (e.g. `America/New_York`). Used to apply local calling hours. |\n| `additional_info` | no | Free-form JSON object for any partner-specific context you want stored on the task. |\n\n---\n\n### Batch response\n\nThe top-level `status` summarises the entire batch:\n\n| status | meaning |\n|--------|---------|\n| `SUCCESS` | All items have status `created` or `duplicate` |\n| `PARTIAL_SUCCESS` | Mix of successful and failed items |\n| `FAILURE` | All items failed |\n\nEach item is processed **atomically** — every resource it touches (target, `for`, each\n`focus[]`, and the task) is written in a single transaction and committed only after the\ndownstream SNOW sync succeeds. If anything fails (validation, DB, or SNOW sync), the whole\nitem is rolled back — **nothing is persisted** — and it is reported as `failed`. Retry the\nfull payload; resubmission is idempotent via `external_id`.\n\nEach item in `results` carries its own `status`:\n\n| per-item status | meaning |\n|-----------------|---------|\n| `created` | Task (and all its resources) successfully created and synced |\n| `duplicate` | A task with this `external_id` already exists — the task is not re-created, but its `target`/`for`/`focus` resources are refreshed (re-upsert + SNOW sync). A transient SNOW failure during the refresh returns `failed` (retryable with the same `external_id`). |\n| `failed` | Validation error, resource not found, or a downstream failure — the item was rolled back (nothing persisted); see `error` field. Retry the full payload. |\n\n---\n\n### HTTP response codes\n\n| code | when |\n|------|------|\n| `200 OK` | All items resolved to `created` or `duplicate` |\n| `207 Multi-Status` | Mix of item statuses (at least one `failed`) |\n| `400 Bad Request` | Request body is empty |\n| `401 Unauthorized` | Missing or invalid authentication token |\n| `422 Unprocessable Entity` | Request body fails schema validation (missing required field, wrong type) |\n| `500 Internal Server Error` | Unexpected server error |","operationId":"ingest_tasks_api_v1_tasks_post","requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/TaskItem"},"type":"array","maxItems":10,"title":"Payload"},"examples":{"patient_upsert_with_appointment":{"summary":"Patient outreach — new patient + upcoming appointment","description":"Most common pattern. Upsert a patient and link to an upcoming appointment as the reason for outreach. HAI will create the patient record if not found, then schedule the outreach task.","value":[{"target":{"resource_type":"Patient","action":"upsert","data":{"mrn":"MRN-001","first_name":"Jane","last_name":"Doe","date_of_birth":"1985-04-12","phone":"555-123-4567","gender":"female","email":"jane.doe@example.com","language":"en"}},"focus":{"resource_type":"Appointment","action":"upsert","data":{"appointment_id":"APT-789","start":"2026-03-15T09:00:00Z","end":"2026-03-15T09:30:00Z","appointment_type":"office_visit","provider_name":"Dr. Jane Smith"}},"task":{"external_id":"TASK-001","task_tag":"pre_appointment_reminder","task_group":"march_2026_reminders","priority":"routine","requested_start":"2026-03-14T08:00:00Z","requested_end":"2026-03-15T08:00:00Z","timezone":"America/New_York","additional_info":{"department":"cardiology","visit_reason":"annual checkup"}}}]},"patient_reference_with_medication":{"summary":"Medication outreach — existing patient + medication request","description":"Use action=reference when the patient already exists in HAI. HAI looks up the patient by MRN only — no demographic update. Returns status=failed if the patient is not found.","value":[{"target":{"resource_type":"Patient","action":"reference","data":{"mrn":"MRN-001"}},"focus":{"resource_type":"MedicationRequest","action":"upsert","data":{"rx_number":"RX-55443","medication_name":"Lisinopril 10mg","days_supply":30,"refills_remaining":2}},"task":{"external_id":"TASK-003","task_tag":"medication_adherence_followup","priority":"routine","requested_start":"2026-03-10T08:00:00Z","requested_end":"2026-03-17T20:00:00Z","timezone":"America/Los_Angeles"}}]},"practitioner_outreach_with_patient":{"summary":"Provider outreach — practitioner (target) + patient as focus","description":"Use when the AI agent contacts a provider about a specific patient. Target is the Practitioner (who to call), focus is the Patient (context). action=reference on focus means the patient already exists in HAI.","value":[{"target":{"resource_type":"Practitioner","action":"upsert","data":{"npi":"1234567890","provider_name":"Dr. John Smith","phone":"555-987-6543","specialty":"internal_medicine"}},"focus":{"resource_type":"Patient","action":"reference","data":{"mrn":"MRN-001"}},"task":{"external_id":"TASK-002","task_tag":"provider_lab_result_notification","priority":"urgent","timezone":"America/Chicago","additional_info":{"result_type":"HbA1c","result_value":"8.2%"}}}]},"provider_and_patient_upsert":{"summary":"Provider + patient (both new) — practitioner target, patient beneficiary (for), medication focus","description":"Generic provider-and-patient flow: an AI agent calls a provider about a patient's medication. Target is the Practitioner (who to call); `for` is the Patient beneficiary; `focus` is the MedicationRequest discussed. action=upsert on both target and `for` creates them if new or updates them if they already exist (matched by NPI / MRN). Resending the same `external_id` returns status=duplicate and refreshes all three (re-upsert + SNOW sync).","value":[{"target":{"resource_type":"Practitioner","action":"upsert","data":{"npi":"1987654321","provider_name":"Dr. Maria Garcia","phone":"555-246-8100","specialty":"cardiology"}},"for":{"resource_type":"Patient","action":"upsert","data":{"mrn":"MRN-204","first_name":"Robert","last_name":"Lee","date_of_birth":"1968-09-30","phone":"555-802-4466","gender":"male"}},"focus":[{"resource_type":"MedicationRequest","action":"upsert","data":{"rx_number":"RX-90210","medication_name":"Atorvastatin 20mg","days_supply":90,"quantity":90,"sig":"Take 1 tablet at bedtime"}}],"task":{"external_id":"TASK-204","task_tag":"medication_adherence_followup","priority":"routine","timezone":"America/Los_Angeles"}}]},"batch_mixed":{"summary":"Batch — multiple items in one request","description":"Submit multiple task bundles in a single request. Each item is processed independently — one failure does not cancel other items. Check per-item `status` in the response.","value":[{"target":{"resource_type":"Patient","action":"upsert","data":{"mrn":"MRN-101","first_name":"Alice","last_name":"Brown","date_of_birth":"1990-07-22","phone":"555-111-2222"}},"focus":{"resource_type":"Appointment","action":"upsert","data":{"appointment_id":"APT-101","start":"2026-03-20T10:00:00Z"}},"task":{"external_id":"TASK-101","task_tag":"pre_appointment_reminder","priority":"routine","timezone":"America/New_York"}},{"target":{"resource_type":"Patient","action":"upsert","data":{"mrn":"MRN-102","first_name":"Bob","last_name":"Green","date_of_birth":"1975-11-03","phone":"555-333-4444"}},"focus":{"resource_type":"Appointment","action":"upsert","data":{"appointment_id":"APT-102","start":"2026-03-21T14:00:00Z"}},"task":{"external_id":"TASK-102","task_tag":"pre_appointment_reminder","priority":"routine","timezone":"America/Chicago"}}]}}}},"required":true},"responses":{"200":{"description":"All items processed successfully (all `created` or `duplicate`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"},"example":{"status":"SUCCESS","trace_id":"550e8400-e29b-41d4-a716-446655440000","results":[{"external_id":"TASK-001","task_id":"ice-task-uuid-001","status":"created"}]}}}},"422":{"description":"Request schema validation failed — required field missing or wrong type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"example":{"detail":[{"type":"missing","loc":["body",0,"task","external_id"],"msg":"Field required","input":{}}]}}}},"207":{"description":"Mix of outcomes across items — check per-item `status`","content":{"application/json":{"examples":{"partial_success":{"summary":"One item created, one failed","value":{"status":"PARTIAL_SUCCESS","trace_id":"550e8400-e29b-41d4-a716-446655440001","results":[{"external_id":"TASK-101","task_id":"ice-task-uuid-101","target_id":"ice-patient-uuid-101","focus_id":"ice-appt-uuid-101","status":"created"},{"external_id":"TASK-102","status":"failed","error":"Patient with action='reference' not found for mrn=MRN-999"}]}},"all_failed":{"summary":"All items failed","value":{"status":"FAILURE","trace_id":"550e8400-e29b-41d4-a716-446655440002","results":[{"external_id":"TASK-201","status":"failed","error":"Patient with action='upsert' is missing required fields in data: ['first_name']"}]}},"duplicate":{"summary":"Task already submitted","value":{"status":"SUCCESS","trace_id":"550e8400-e29b-41d4-a716-446655440003","results":[{"external_id":"TASK-001","task_id":"ice-task-uuid-001","status":"duplicate"}]}}}}}},"400":{"description":"Empty request body","content":{"application/json":{"example":{"detail":"Request body must contain at least one item"}}}},"401":{"description":"Missing or invalid authentication token","content":{"application/json":{"example":{"detail":"Unauthorized"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"example":{"detail":"An unexpected error occurred. Please try again later."}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"Appointment":{"properties":{"appointment_id":{"type":"string","maxLength":100,"minLength":1,"title":"Appointment Id","description":"Unique external appointment ID"},"appointment_date":{"type":"string","title":"Appointment Date","description":"Appointment start date/time in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)"},"appointment_end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointment End Date","description":"Appointment end date/time in ISO 8601 format"},"appointment_reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Appointment Reason","description":"Reason for appointment"},"appointment_type":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Appointment Type","description":"Type of appointment (e.g., Routine, Follow-up)"},"appointment_status":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Appointment Status","description":"FHIR appointment status","default":"booked"},"appointment_location_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Appointment Location Name","description":"Name of appointment location"},"appointment_location_address":{"anyOf":[{"$ref":"#/components/schemas/AppointmentAddress"},{"type":"null"}],"description":"Address of appointment location"},"appointment_notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Appointment Notes","description":"Additional notes for appointment"}},"additionalProperties":false,"type":"object","required":["appointment_id","appointment_date"],"title":"Appointment","description":"Individual appointment data"},"AppointmentAddress":{"properties":{"line1":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Line1","description":"Address line 1"},"line2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Line2","description":"Address line 2"},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"City","description":"City"},"state":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"State","description":"State"},"zip":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Zip","description":"ZIP/Postal code"},"country":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Country","description":"Country, defaults to US","default":"US"}},"additionalProperties":false,"type":"object","title":"AppointmentAddress","description":"Address information for appointment location"},"AppointmentRequest":{"properties":{"contact":{"$ref":"#/components/schemas/ContactInfo","description":"Contact demographic information (matches contacts API naming)"},"appointments":{"items":{"$ref":"#/components/schemas/Appointment"},"type":"array","maxItems":100,"minItems":1,"title":"Appointments","description":"List of appointments (1-100)"}},"additionalProperties":false,"type":"object","required":["contact","appointments"],"title":"AppointmentRequest","description":"Main request body for appointments API"},"ContactInfo":{"properties":{"mrn":{"type":"string","maxLength":50,"minLength":1,"title":"Mrn","description":"Medical Record Number (mandatory)"},"first_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"First Name","description":"Contact first name (optional)"},"last_name":{"anyOf":[{"type":"string","maxLength":100,"minLength":1},{"type":"null"}],"title":"Last Name","description":"Contact last name (optional)"},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Of Birth","description":"Contact date of birth in YYYY-MM-DD format (optional)"},"additional_info":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Additional Info","description":"Additional contact information as key-value pairs. Will be stored in FHIR extension format with url and valueString."}},"additionalProperties":false,"type":"object","required":["mrn"],"title":"ContactInfo","description":"Contact demographic information for validation - only MRN is mandatory"},"ContactWithMedicationAndOutreach":{"properties":{"mrn":{"type":"string","minLength":1,"title":"Mrn","description":"Medical record number (MRN)"},"first_name":{"type":"string","minLength":1,"title":"First Name","description":"First name of the patient"},"middle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Middle","description":"Middle name of the patient"},"last_name":{"type":"string","minLength":1,"title":"Last Name","description":"Last name of the patient"},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Of Birth","description":"Patient's date of birth (YYYY-MM-DD). Required unless outreach_name is 'Diabetes Chat'"},"next_call_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Call Date","description":"Patient's next call date (YYYY-MM-DD)"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Patient's gender (male, female, other). Required unless outreach_name is 'Diabetes Chat'"},"phone_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Number","description":"Patient's phone number (E.164 format recommended). Required unless outreach_name is 'Diabetes Chat'"},"do_not_call":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Do Not Call","description":"Indicates if the patient should not be contacted. Explicit true/false indicates that a patient should/should not be DNC'd.","default":false},"is_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Deleted","description":"Indicates if the patient record should be marked as archived. If true, sets entity_status='archived'. If false or not provided, sets entity_status='active'."},"deceased_boolean":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Deceased Boolean","description":"Indicates the patient is deceased. If true, marks the patient deceased and sets entity_status='archived'. Once a patient is marked deceased, ICE will not allow reverting to non-deceased via this field. If false or not provided, no change is applied."},"provider_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Name","description":"Name of the primary care provider"},"preferred_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferred Language","description":"Preferred language code (ISO 639-1)"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone","description":"Patient's timezone (IANA format)"},"outreach_name":{"type":"string","title":"Outreach Name","description":"Type of outreach for this patient"},"additional_info":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Additional Info","description":"Additional information about the patient in JSON format"},"address_line1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line1","description":"Address line 1 (Street and number)"},"address_line2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address Line2","description":"Address line 2 (Additional street details)"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City of residence"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"State code (US State Abbreviations)"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of residence"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code","description":"Postal or ZIP code"},"procedure_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Procedure Code","description":"CPT code representing the upcoming procedure"},"procedure_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Procedure Date","description":"Date and time of the procedure"},"procedure_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Procedure Type","description":"Description of the procedure"},"procedure_site":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Procedure Site","description":"Site where the procedure will be performed"},"discharge_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Discharge Date","description":"Date of patient discharge (if applicable)"},"upcoming_procedure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Reason","description":"The reason for the procedure"},"upcoming_procedure_arrival_buffer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Arrival Buffer","description":"Time patient should arrive before procedure start"},"upcoming_procedure_arrival_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Arrival Location","description":"Arrival location for procedure"},"upcoming_procedure_prep":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Prep","description":"Preparation instructions for procedure"},"upcoming_procedure_required_clearances":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Required Clearances","description":"Required clearances for the upcoming procedure"},"upcoming_procedure_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Address","description":"Address for the upcoming procedure"},"upcoming_procedure_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Upcoming Procedure Date","description":"Date and time of upcoming procedure"},"upcoming_procedure_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Procedure Type","description":"Type of upcoming procedure"},"upcoming_appointment_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Upcoming Appointment Date","description":"Date and time of upcoming appointment"},"upcoming_appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Appointment Type","description":"Type of upcoming appointment"},"upcoming_appointment_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Appointment Reason","description":"Reason for upcoming appointment"},"upcoming_appointment_clinic_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Appointment Clinic Name","description":"Clinic name for upcoming appointment"},"upcoming_appointment_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upcoming Appointment Address","description":"Address for upcoming appointment"},"previous_appointment_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Previous Appointment Date","description":"Date and time of previous appointment"},"previous_appointment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Appointment Type","description":"Type of previous appointment"},"previous_appointment_clinic_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Appointment Clinic Name","description":"Clinic name of previous appointment"},"care_location_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Care Location Slug","description":"Care location slug for primary care location"},"related_persons":{"anyOf":[{"items":{"$ref":"#/components/schemas/RelatedPerson"},"type":"array","maxItems":10},{"type":"null"}],"title":"Related Persons","description":"List of related persons associated with the patient (e.g., emergency contacts, caregivers)"},"medications":{"anyOf":[{"items":{"$ref":"#/components/schemas/src__external__api__schemas__product__v1__contacts__MedicationRequest"},"type":"array"},{"type":"null"}],"title":"Medications","description":"List of medications for this patient"},"outreach":{"anyOf":[{"$ref":"#/components/schemas/OutreachRequest"},{"type":"null"}],"description":"Outreach information for this patient"}},"additionalProperties":false,"type":"object","required":["mrn","first_name","last_name","outreach_name"],"title":"ContactWithMedicationAndOutreach","description":"Extended Contact schema that includes optional medications and outreach data"},"ContactsBundleRequest":{"properties":{"contacts":{"items":{"$ref":"#/components/schemas/ContactWithMedicationAndOutreach"},"type":"array","title":"Contacts","description":"List of contacts with optional medications and outreach"}},"additionalProperties":false,"type":"object","required":["contacts"],"title":"ContactsBundleRequest","description":"Request schema for combined contacts with medications and outreach"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MedicationRequestBody":{"items":{"$ref":"#/components/schemas/MedicationRequestEntry"},"type":"array","minItems":1,"title":"MedicationRequestBody","description":"List of medication entries"},"MedicationRequestEntry":{"properties":{"mrn":{"type":"string","minLength":1,"title":"Mrn","description":"Medical record number (MRN)"},"medications":{"items":{"$ref":"#/components/schemas/src__external__api__schemas__product__v1__medication_request__MedicationRequest"},"type":"array","minItems":1,"title":"Medications","description":"List of medications for the patient"}},"additionalProperties":false,"type":"object","required":["mrn","medications"],"title":"MedicationRequestEntry"},"OutreachCancelRequest":{"properties":{"external_contact_id":{"type":"string","title":"External Contact Id","description":"External contact ID (MRN)"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for cancellation"}},"type":"object","required":["external_contact_id"],"title":"OutreachCancelRequest","description":"Request schema for outreach cancellation"},"OutreachCancelResponse":{"properties":{"version":{"type":"string","title":"Version","description":"API version","default":"1.0"},"status":{"type":"string","title":"Status","description":"Overall status: 'success', 'not_found', or 'error'"},"message":{"type":"string","title":"Message","description":"Human-readable status message"},"cancelled_outreaches":{"anyOf":[{"items":{"$ref":"#/components/schemas/OutreachInfo"},"type":"array"},{"type":"null"}],"title":"Cancelled Outreaches","description":"List of cancelled outreaches"},"patient_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Patient Id","description":"HAI patient ID (for debugging)"}},"type":"object","required":["status","message"],"title":"OutreachCancelResponse","description":"Response schema for outreach cancellation API"},"OutreachCreateRequest":{"properties":{"contact_id":{"type":"string","title":"Contact Id","description":"Patient MR (Medical Record Number) - stored in identifier_value where identifier_type='MR'"},"campaign_id":{"type":"string","title":"Campaign Id","description":"Campaign ID"},"scheduled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scheduled At","description":"ISO datetime string - must be at least 1 hour in the past and at most 48 hours in the future. Defaults to 10 minutes from now if not provided"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"ISO datetime string - defaults to 48 hours from now if not provided"},"dry_run":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Dry Run","description":"Dry run mode","default":false}},"type":"object","required":["contact_id","campaign_id"],"title":"OutreachCreateRequest","description":"Request schema for creating outreach for campaign"},"OutreachCreateResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Overall status: 'success' or 'error'"},"message":{"type":"string","title":"Message","description":"Human-readable status message"},"outreach_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outreach Id","description":"Created outreach ID"}},"type":"object","required":["status","message"],"title":"OutreachCreateResponse","description":"Response schema for outreach creation API"},"OutreachInfo":{"properties":{"outreach_id":{"type":"string","title":"Outreach Id","description":"Unique outreach identifier"},"status":{"type":"string","title":"Status","description":"New status of the outreach"}},"type":"object","required":["outreach_id","status"],"title":"OutreachInfo","description":"Information about a cancelled outreach"},"OutreachRequest":{"properties":{"campaign_id":{"type":"string","title":"Campaign Id","description":"Campaign ID for the outreach"},"scheduled_at":{"type":"string","title":"Scheduled At","description":"ISO datetime string - must be at least 1 hour in the past and at most 48 hours in the future"},"expires_at":{"type":"string","title":"Expires At","description":"ISO datetime string - must be at least 1 hour in the future"},"action":{"anyOf":[{"type":"string","enum":["create","cancel"]},{"type":"null"}],"title":"Action","description":"Action to perform: create or cancel","default":"create"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason for cancellation (if action is cancel)"},"dry_run":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Dry Run","description":"Dry run mode","default":false}},"additionalProperties":false,"type":"object","required":["campaign_id","scheduled_at","expires_at"],"title":"OutreachRequest","description":"Schema for outreach data within contact"},"RelatedPerson":{"properties":{"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name","description":"First name of the related person"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name","description":"Last name of the related person"},"datetime":{"anyOf":[{"$ref":"#/components/schemas/RelatedPersonDatetime"},{"type":"null"}],"description":"Datetime range for the relationship"},"is_primary_contact":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Primary Contact","description":"Indicates if this is the primary contact person"},"relationship_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Relationship Type","description":"Type of relationship role (e.g., guardian, caregiver, emergency contact)"},"personal_relation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Personal Relation","description":"Personal relation to the patient (e.g., spouse, parent, child, caregiver)"}},"additionalProperties":false,"type":"object","title":"RelatedPerson","description":"Related person associated with the patient (e.g., emergency contact, caregiver)."},"RelatedPersonDatetime":{"properties":{"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start","description":"Start date/time of the relationship"},"end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End","description":"End date/time of the relationship"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone","description":"Timezone for the datetime values"}},"additionalProperties":false,"type":"object","title":"RelatedPersonDatetime","description":"Datetime range for the related person relationship."},"ResourceAction":{"type":"string","enum":["upsert","reference"],"title":"ResourceAction","description":"Action to perform on a resource when processing a task bundle.\n\nUPSERT    — create or update the resource using fields in data.\nREFERENCE — look up an existing resource by its lookup key only."},"TaskItem":{"properties":{"target":{"$ref":"#/components/schemas/TaskResource","description":"The entity the agent will contact (Patient or Practitioner)"},"for":{"anyOf":[{"$ref":"#/components/schemas/TaskResource"},{"type":"null"}],"description":"The Patient beneficiary (optional). If omitted, ICE derives it."},"focus":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskResource"},"type":"array"},{"type":"null"}],"title":"Focus","description":"Clinical resources the call is about (list; e.g. Appointment, MedicationRequest)"},"task":{"$ref":"#/components/schemas/TaskMeta"}},"additionalProperties":false,"type":"object","required":["target","task"],"title":"TaskItem","description":"One item in the batch — target + optional beneficiary (`for`) + focus[] + task."},"TaskItemResult":{"properties":{"external_id":{"type":"string","title":"External Id"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"target_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Id"},"focus_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Focus Id"},"status":{"type":"string","title":"Status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["external_id","status"],"title":"TaskItemResult","description":"Result for a single item in the batch."},"TaskMeta":{"properties":{"external_id":{"type":"string","minLength":1,"title":"External Id","description":"Partner-supplied task identifier (unique per partner)"},"task_tag":{"type":"string","minLength":1,"title":"Task Tag","description":"Task classification / reason code (e.g. pre_appointment_reminder)"},"task_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Group","description":"Batch / campaign group identifier"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority","description":"FHIR RequestPriority: routine | urgent | asap | stat","default":"routine"},"requested_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested Start","description":"ISO 8601 UTC — earliest time to begin outreach"},"requested_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested End","description":"ISO 8601 UTC — hard cutoff / expiration for outreach"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone","description":"IANA timezone"},"hippocratic_care_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hippocratic Care Location Id","description":"Hippocratic care-location id. Not the ICE row UUID."},"additional_info":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Additional Info","description":"Free-form partner-specific context stored on the task"}},"additionalProperties":false,"type":"object","required":["external_id","task_tag"],"title":"TaskMeta","description":"Task definition — controls outreach timing and classification."},"TaskResource":{"properties":{"resource_type":{"type":"string","title":"Resource Type","description":"FHIR resource type: Patient | Practitioner | Appointment | Encounter | MedicationRequest | Condition | ..."},"action":{"$ref":"#/components/schemas/ResourceAction","description":"upsert: create or update the resource using data. reference: look up existing resource by its lookup key."},"data":{"type":"object","title":"Data","description":"Resource fields. Required fields depend on resource_type and action. For action=upsert, must include all required fields for that resource_type. For action=reference, must include only the lookup key (e.g. mrn for Patient, npi for Practitioner, appointment_id for Appointment)."}},"additionalProperties":false,"type":"object","required":["resource_type","action","data"],"title":"TaskResource","description":"Generic polymorphic resource reference — used for both target and focus.\n\naction=\"upsert\":\n    ICE creates or updates the resource. `data` must contain all required\n    fields for that resource_type (validated by the processor).\n\naction=\"reference\":\n    ICE looks up an existing resource by its lookup key. `data` must contain\n    only the lookup key for that resource_type.\n    Fails with status=failed if the resource is not found."},"TaskResponse":{"properties":{"status":{"type":"string","title":"Status"},"trace_id":{"type":"string","title":"Trace Id"},"results":{"items":{"$ref":"#/components/schemas/TaskItemResult"},"type":"array","title":"Results"}},"type":"object","required":["status","trace_id","results"],"title":"TaskResponse","description":"Batch response — overall status + per-item results."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"src__external__api__schemas__product__v1__contacts__MedicationRequest":{"properties":{"medication_name":{"type":"string","title":"Medication Name","description":"Name of the medication"},"dosage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dosage","description":"Dosage information"},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency","description":"Frequency of medication"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date","description":"Start date of medication (YYYY-MM-DD)"},"prescriber_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prescriber Name","description":"Name of the prescriber"}},"additionalProperties":false,"type":"object","required":["medication_name"],"title":"MedicationRequest","description":"Schema for medication data within contact"},"src__external__api__schemas__product__v1__medication_request__MedicationRequest":{"properties":{"medication":{"type":"string","minLength":1,"title":"Medication","description":"Name of the medication"},"prescription":{"type":"string","minLength":1,"title":"Prescription","description":"Prescription details including dosage and frequency"},"status":{"type":"string","title":"Status","description":"Status of the medication (active, discontinued, completed)"}},"additionalProperties":false,"type":"object","required":["medication","prescription","status"],"title":"MedicationRequest"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"webhookAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication for webhook endpoints"}}},"tags":[{"name":"Partner API v1","description":"Partner integration endpoints for submitting patient data and requests"},{"name":"Webhooks","description":"Webhook endpoints that Hippocratic AI sends to partner systems"}],"webhooks":{"call-summary":{"post":{"summary":"Call Summary Webhook","description":"Hippocratic AI sends call summary data to the partner's webhook endpoint after completing a patient interaction. Partners should implement this webhook endpoint to receive call summaries.\n\n**Retry Policy:** If the webhook delivery fails (non-2xx response or network error), Hippocratic AI will automatically retry the delivery 3-5 times with 30-minute intervals between attempts. After the maximum retry attempts, the delivery will be marked as permanently failed.\n\n**Compatibility**\n- New optional fields and enum values may appear without notice. Partners MUST ignore unknown fields and unknown enum values.\n- Field removals, type changes, and enum-value removals are breaking and will be coordinated in advance.\n- Optional fields are typically sent as `\"\"` / `[]` rather than omitted. Treat both as \"no value\".\n- A partner receives exactly one of the two contracts (`call-summary` or `call-summary-legacy`). Confirm with your DA. Payloads are not interchangeable.\n- Deliveries may be retried after non-2xx responses. `call.call_id` is stable across retries — deduplicate on it.\n- The V2 `version` field signals major contract changes only. Field and enum additions do not bump it.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["version","call_summary"],"properties":{"version":{"type":"string","description":"Call summary format version","example":"2.0"},"call_summary":{"type":"object","description":"Complete call summary data","required":["call_id"],"properties":{"call_id":{"type":"string","format":"uuid","description":"Unique identifier for the call"},"datetime_of_call":{"type":"string","description":"Local datetime string"},"call_duration_seconds":{"type":"string","description":"Call duration in seconds"},"initiated_by_patient":{"type":"boolean","description":"Whether the patient initiated the call"},"language":{"type":"string","description":"Language used in call"},"enhanced_disposition":{"type":"string","description":"How the call ended. Computed by ICE: voicemail detection from `call_end_reason`, transfer outcomes from `dispositions[].call_outcome`, fallback to `dispositions[].disposition`.","enum":["call_completed","call_hung_up","no_answer","failed_verification","call_failed","immediate_hang_up","voicemail_detected","transferred","transfer_failed","hung_up_during_transfer"]},"appointment_id":{"type":"string","description":"External appointment identifier injected when an appointment lookup succeeds (scheduling scripts only)."},"call_url":{"type":"string","format":"uri","description":"URL to view the call summary in our Portal"},"call_type":{"type":"string","description":"Shorthand for the script or use case"},"customer_patient_id":{"type":"string","description":"Medical record number"},"patient_name":{"type":"object","description":"Patient's structured name","properties":{"first":{"type":"string"},"last":{"type":"string"}}},"date_of_birth":{"type":"string","format":"date","description":"DOB in YYYY-MM-DD format"},"gender":{"type":"string","description":"Patient gender (FHIR-aligned).","enum":["unknown","male","female","other","transgender/him","transgender/her","nonbinary","unspecified/they"]},"phone_number":{"type":"string","description":"Contact number"},"care_location_name":{"type":"string","description":"Clinic or care facility"},"physician_name":{"type":"string","description":"Physician involved (may be empty)"},"conversation_summary":{"type":"string","description":"Free-text summary of call"},"do_not_call":{"type":"boolean","description":"If true, summary questions should indicate why"},"medication_summaries":{"type":"array","description":"Medications from the patient record","items":{"type":"object","properties":{"name":{"type":"string","description":"Medication name."},"type":{"type":"string","description":"Medication category. Typical values: \"New Rx\", \"Old Rx\", \"Self-Reported\"."},"dosage":{"type":"string","description":"Free-text dosage."},"adherence":{"type":"string","description":"Adherence reported on the call. Typical values: \"Yes\", \"No\", \"Unknown\", \"N/A\"."},"notes":{"type":"string","description":"Free-text notes."}}}},"device_summaries":{"type":"array","description":"Medical devices discussed","items":{"type":"object","properties":{"model":{"type":"string","description":"Device model."},"adherence":{"type":"string","description":"Adherence reported on the call. Typical values: \"Adherent\", \"Delinquent\", \"N/A\"."},"measurement":{"type":"string","description":"Free-text measurement / reading."},"notes":{"type":"string","description":"Free-text notes."}}}},"schedule_engine_summaries":{"type":"array","description":"Appointment scheduling outputs produced during the call (scheduling scripts only).","items":{"type":"object","properties":{"output_name":{"type":"string","description":"Output identifier. Default \"scheduling_summary\"."},"output_type":{"type":"string","description":"Engine that produced the output.","enum":["ehr_summary","interjection","notes","mcm_summary","offline_errors","kickout","scheduling","form_fill","mdr_detection","adverse_event_detection","call_errors","escalation_reconciliation","audio_summary","ai_screener_detected","custom_call_success","analytics"]},"output_value":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Shape varies by scheduling tool. New keys may appear with new integrations. Includes a `booking_successful` boolean."}}}},"summary_question_answers":{"type":"array","description":"Responses to structured questions. Items where `hide_from_summary_display=true` are filtered out before delivery.","items":{"type":"object","properties":{"question":{"type":"string","description":"Display question text."},"answer":{"type":"string","description":"Patient's response."},"choices":{"type":"array","items":{"type":"string"},"description":"Available answer options."},"response_type":{"type":"string","description":"Shape of the question/answer.","enum":["choices_yes_no_unknown","choices_yes_no","measurement","open_ended","multi_select","multiple_choice","mcm_general","timestamp"]},"answer_indexes":{"type":"array","items":{"type":"integer"},"description":"Indexes into `choices` matching the patient's answer (choice-based types)."},"section":{"type":"string","description":"Section where question was asked."},"external_id":{"type":"string","description":"External-system mapping identifier."},"variable_name":{"type":"string","description":"Internal variable name."},"default_value":{"description":"Default answer value."},"display_value":{"description":"Human-friendly display value."},"prompt_question":{"type":"string","description":"LLM-specific prompt used to elicit the answer."},"notes":{"type":"string","description":"Additional notes."},"hide_from_summary_display":{"type":"boolean","description":"Always false in delivered payloads (true items are filtered out)."}}}},"follow_up_items":{"type":"array","items":{"type":"string"},"description":"Free-text follow-up actions identified during the call."},"todo_summaries":{"type":"array","description":"Task items generated from the call.","items":{"type":"object","properties":{"todo_id":{"type":"string","format":"uuid"},"partner_id":{"type":"string","format":"uuid"},"action":{"type":"string","description":"Action to be taken."},"due_date":{"type":"string","format":"date-time","description":"ISO-8601 UTC due date."},"completed_date":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601 UTC completion timestamp; null when not completed."},"priority":{"type":"string","description":"Todo priority.","enum":["urgent","high","medium","low"]},"todo_status":{"type":"string","description":"Todo lifecycle status.","enum":["draft","pending","completed","archived"]},"todo_type":{"type":"string","description":"Todo category.","enum":["unknown","patient_escalation","patient_escalation_failure","patient_call_review","patient_callback","clinical_review","client_follow_up","escalation_case_review","data_annotation"]},"todo_metadata":{"type":"object","nullable":true,"additionalProperties":true,"description":"Free-form, varies by `todo_type`. Not stable."},"external_id":{"type":"string","nullable":true,"description":"External-system identifier for this todo."}}}},"escalation_summaries":{"type":"array","description":"Clinical escalations (kickouts) triggered during the call.","items":{"type":"object","properties":{"kickout_id":{"type":"string","description":"Stable identifier for the escalation rule that fired."},"display_name":{"type":"string","description":"Human-readable escalation name."},"severity":{"type":"string","description":"Triage color. `in_progress` indicates a kickout that has started but not yet been color-classified.","enum":["in_progress","white","blue","green","yellow","amber","orange","purple","red"]},"summary":{"type":"string","description":"Generated summary of the escalation context."},"utp_status":{"type":"string","description":"Patient transfer status for this kickout (if applicable)."}}}},"form_fill_summaries":{"type":"array","description":"Structured form responses captured during the call. Fields are harmonized with `summary_question_answers` plus form-specific extensions.","items":{"type":"object","properties":{"question":{"type":"string","description":"Display question text."},"answer":{"type":"string","description":"Patient's response."},"choices":{"type":"array","items":{"type":"string"},"description":"Available answer options."},"response_type":{"type":"string","description":"Shape of the form question. Same enum as `summary_question_answers.response_type`.","enum":["choices_yes_no_unknown","choices_yes_no","measurement","open_ended","multi_select","multiple_choice","mcm_general","timestamp"]},"answer_indexes":{"type":"array","items":{"type":"integer"},"description":"Indexes into `choices` matching the patient's answer."},"external_id":{"type":"string","description":"External-system identifier for this form question."},"variable_name":{"type":"string","description":"Internal variable name (sourced from Snow's `question_id`)."},"external_options":{"type":"array","items":{"type":"string"},"description":"External-system equivalents of `choices`."},"formatted_options":{"type":"string","description":"Pre-formatted options string for display."},"changed":{"type":"boolean","description":"True if the answer was edited after initial capture."},"applicable":{"type":"boolean","description":"True if the question was applicable to this patient (default true)."},"skipped":{"type":"boolean","description":"True if the question was intentionally skipped."},"asked":{"type":"boolean","description":"True if the question was asked during the call."},"should_highlight":{"type":"boolean","description":"Hint to UI to highlight this answer."},"arbitration_status":{"type":"string","description":"Status of any post-call arbitration / review on this answer."},"created_by_user_id":{"type":"string","format":"uuid","description":"Internal user ID that captured this form answer."}}}},"hippocratic_ids":{"type":"object","description":"Internal system identifiers primarily for debugging. All seven fields are always present; each may be an empty string if not set on this call.","properties":{"patient_id":{"type":"string","description":"Hippocratic patient UUID. May be an empty string."},"partner_id":{"type":"string","description":"Partner UUID. May be an empty string."},"partner_care_location_id":{"type":"string","description":"Partner care-location UUID. May be an empty string."},"script_id":{"type":"string","description":"Script UUID. May be an empty string."},"agent_id":{"type":"string","description":"Agent UUID. May be an empty string."},"outreach_id":{"type":"string","description":"Outreach UUID. May be an empty string."},"scenario_id":{"type":"string","description":"Scenario UUID. May be an empty string."}}},"custom_variables":{"type":"object","additionalProperties":true,"description":"Free-form, partner-configured. Keys and shape are not stable."}}}},"example":{"version":"2.0","call_summary":{"call_id":"3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","customer_patient_id":"XX0101506","patient_name":{"last":"Smith","first":"John"},"date_of_birth":"1937-04-22","language":"en","datetime_of_call":"2025-08-20 07:38 PM EDT","call_duration_seconds":"232","initiated_by_patient":true,"physician_name":"","conversation_summary":"Patient reports they have filled their Simvastatin and Metformin prescriptions...","enhanced_disposition":"call_hung_up","gender":"male","phone_number":"+15125551212","care_location_name":"Test Location","call_url":"https://portal.us.hippocraticai.com/call/3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","call_type":"preop_ortho","do_not_call":false,"medication_summaries":[],"device_summaries":[],"summary_question_answers":[],"follow_up_items":[],"todo_summaries":[],"escalation_summaries":[],"form_fill_summaries":[],"custom_variables":{},"hippocratic_ids":{"patient_id":"xxx","partner_id":"xxx","partner_care_location_id":"xxx","script_id":"xxx","agent_id":"xxx","outreach_id":"xxx","scenario_id":"xxx"}}}}}}},"responses":{"200":{"description":"Webhook received and processed successfully"},"201":{"description":"Webhook received and call summary created"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook authentication"},"500":{"description":"Internal server error processing webhook"}},"security":[{"webhookAuth":[]}]}},"call-summary-legacy":{"post":{"summary":"Call Summary Webhook (Legacy / Raw Format)","description":"Legacy call summary payload used by select partners (e.g., LeanTaas / Pinnacle Orthopedics). Hippocratic AI POSTs this JSON after each completed call.\n\nUnlike the standard `call-summary` webhook (which delivers a flat, versioned `{version, call_summary}` envelope), this payload is split across a top-level `call` object (call metadata, dispositions) and `json_summary` object (clinical summary). Three rendered representations of the summary — `pdf_summary` (base64 PDF), `html_summary`, `txt_summary` — are also included.\n\n**Retry Policy:** If the webhook delivery fails (non-2xx response or network error), Hippocratic AI will automatically retry the delivery 3-5 times with 30-minute intervals between attempts.\n\n**Compatibility**\n- New optional fields and enum values may appear without notice. Partners MUST ignore unknown fields and unknown enum values.\n- Field removals, type changes, and enum-value removals are breaking and will be coordinated in advance.\n- Optional fields are typically sent as `\"\"` / `[]` rather than omitted. Treat both as \"no value\".\n- A partner receives exactly one of the two contracts (`call-summary` or `call-summary-legacy`). Confirm with your DA. Payloads are not interchangeable.\n- Deliveries may be retried after non-2xx responses. `call.call_id` is stable across retries — deduplicate on it.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["call","json_summary"],"properties":{"call":{"type":"object","description":"Call metadata and dispositions for this interaction.","required":["call_id"],"properties":{"call_id":{"type":"string","format":"uuid","description":"Unique identifier for the call."},"call_type":{"type":"string","description":"Call session type.","enum":["telephone","web_chat","web_voice","autonomous"]},"call_status":{"type":"string","nullable":true,"description":"Terminal call status.","enum":["call_initiated","call_in_progress","call_completed","call_errored","call_third_party_interrupt","call_failed_to_connect","call_failed_with_error_code","call_started","call_dropped","call_restarted","call_connected","call_finished"]},"call_direction":{"type":"string","nullable":true,"description":"Direction of the call (e.g., \"inbound\", \"outbound\")."},"encounter_id":{"type":"string","format":"uuid","description":"Identifier for the communication encounter."},"initiated_by_patient":{"type":"boolean","description":"True if the patient initiated the call (inbound)."},"call_purpose":{"type":"string","description":"Free-text purpose configured on the script."},"created_at":{"type":"string","format":"date-time","description":"ISO-8601 UTC timestamp when the call record was created."},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601 UTC timestamp when the call started."},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601 UTC timestamp when the call ended."},"call_channel":{"type":"string","description":"Underlying delivery channel (e.g., \"twilio\", \"web\", \"whatsapp\")."},"created_by_user_id":{"type":"string","format":"uuid","description":"Internal user ID that created the call record."},"duration":{"type":"number","format":"float","nullable":true,"description":"Call duration in seconds."},"call_host_url_base":{"type":"string","nullable":true,"description":"Base URL of the host that handled the call."},"call_end_reason":{"type":"string","nullable":true,"description":"Reason the call ended.","enum":["unknown","user_ended_call_regular","user_ended_call_disconnect","user_ended_call_busy","user_ended_chat_logged_out","user_ended_chat_expired","system_ended_call_regular","system_ended_call_emergency_before_dob","system_ended_call_error","system_ended_call_timeout","system_ended_call_kickout","system_ended_call_identity_verification","system_ended_call_dob_verification","system_ended_call_voicemail","system_ended_call_redteam","system_ended_call_other_party_disconnect","system_ended_call_failed_to_connect","system_ended_call_transfer_fallback_initiated","system_ended_call_transfer_failed","system_ended_call_delivered_voicemail","system_ended_call_ivr_terminal_loop","system_ended_call_ivr_voicemail_detected","system_ended_call_ivr_on_hold_timeout"]},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code used in the call (e.g., \"en\", \"es\")."},"phone_number":{"type":"string","nullable":true,"description":"Patient phone number. Typically null; canonical phone is `json_summary.phone_number`."},"telephony_sid":{"type":"string","nullable":true,"description":"Telephony provider call SID (e.g., Twilio CallSid)."},"telephony_account_sid":{"type":"string","nullable":true,"description":"Telephony provider account SID."},"telephony_provider":{"type":"string","nullable":true,"description":"Telephony provider.","enum":["twilio","telnyx","unknown"]},"customer_patient_id":{"type":"string","description":"Partner-provided patient identifier (e.g., MRN)."},"dispositions":{"type":"array","description":"Final call disposition(s). Typically a single entry.","items":{"type":"object","properties":{"call_disposition_id":{"type":"string","format":"uuid"},"call_id":{"type":"string","format":"uuid"},"created_by_user_id":{"type":"string","format":"uuid"},"disposition":{"type":"string","description":"How the call concluded.","enum":["call_completed","call_hung_up","no_answer","failed_verification","call_failed","immediate_hang_up"]},"call_outcome":{"type":"string","nullable":true,"description":"Post-call outcome classification.","enum":["successful","transcript_review_required","follow_up_required","no_action","transferred","transfer_failed","patient_hung_up_during_transfer","supervised"]},"custom_call_success_evaluation_status":{"type":"string","nullable":true,"description":"Status of the partner-defined success criteria evaluation.","enum":["not_evaluated","criteria_not_defined","errored","evaluated"]},"custom_call_success":{"type":"boolean","nullable":true,"description":"True if the call met the partner-defined success criteria."},"created_at":{"type":"string","format":"date-time"}}}}}},"json_summary":{"type":"object","description":"Clinical summary of the call (patient demographics, conversation summary, structured outputs).","properties":{"call_id":{"type":"string","format":"uuid","nullable":true,"description":"Same call_id as `call.call_id`."},"patient_name":{"type":"string","description":"Patient name as a single string, format \"Last, First\"."},"date_of_birth":{"type":"string","description":"Patient DOB. Format varies by partner script — typically YYYY-MM-DD."},"datetime_of_call":{"type":"string","description":"Human-readable local datetime of the call (timezone-aware string, e.g., \"2025-08-20 07:38 PM EDT\")."},"physician_name":{"type":"string","description":"Physician associated with the encounter (may be empty)."},"call_purpose":{"type":"string","description":"Free-text purpose configured on the script."},"conversation_summary":{"type":"string","nullable":true,"description":"Free-text summary of the conversation."},"call_disposition":{"type":"string","nullable":true,"description":"Disposition mirrored from `call.dispositions[].disposition`.","enum":["call_completed","call_hung_up","no_answer","failed_verification","call_failed","immediate_hang_up"]},"mrn":{"type":"string","nullable":true,"description":"Patient MRN from the partner record."},"gender":{"type":"string","nullable":true,"description":"Patient gender (FHIR-aligned).","enum":["unknown","male","female","other","transgender/him","transgender/her","nonbinary","unspecified/they"]},"phone_number":{"type":"string","nullable":true,"description":"Patient phone number used for the call."},"care_location_name":{"type":"string","nullable":true,"description":"Clinic or care facility associated with the encounter."},"call_url":{"type":"string","format":"uri","nullable":true,"description":"Portal URL where the call can be reviewed."},"call_type":{"type":"string","nullable":true,"description":"Shorthand for the script / use case. May be overridden by ICE for specific scripts (e.g., \"preop_ortho\", \"preop_clearances\")."},"do_not_call":{"type":"boolean","nullable":true,"description":"If true, downstream systems should suppress further outreach to this patient."},"custom_variables":{"type":"object","nullable":true,"additionalProperties":true,"description":"Free-form, partner-configured. Keys and shape are not stable."},"medication_summaries":{"type":"array","description":"Medications discussed on the call.","items":{"type":"object","properties":{"name":{"type":"string","description":"Medication name."},"type":{"type":"string","description":"Medication category. Typical values: \"New Rx\", \"Old Rx\", \"Self-Reported\"."},"dosage":{"type":"string","description":"Free-text dosage."},"adherence":{"type":"string","description":"Adherence reported on the call. Typical values: \"Yes\", \"No\", \"Unknown\", \"N/A\"."},"notes":{"type":"string","description":"Free-text notes."}}}},"device_summaries":{"type":"array","description":"Medical devices discussed on the call.","items":{"type":"object","properties":{"model":{"type":"string","description":"Device model."},"adherence":{"type":"string","description":"Adherence reported on the call. Typical values: \"Adherent\", \"Delinquent\", \"N/A\"."},"measurement":{"type":"string","description":"Free-text measurement / reading."},"notes":{"type":"string","description":"Free-text notes."}}}},"summary_question_answers":{"type":"array","description":"Responses to structured questions. Items where `hide_from_summary_display=true` are filtered out before delivery.","items":{"type":"object","properties":{"section":{"type":"string","description":"Section / category where the question was asked."},"question":{"type":"string","description":"Display question text."},"answer":{"type":"string","description":"Patient's response."},"response_type":{"type":"string","description":"Shape of the question/answer.","enum":["choices_yes_no_unknown","choices_yes_no","measurement","open_ended","multi_select","multiple_choice","mcm_general","timestamp"]},"choices":{"type":"array","items":{"type":"string"},"description":"Available answer options for choice-based response types."},"external_choices":{"type":"array","items":{"type":"string"},"nullable":true,"description":"External-system equivalents of `choices`."},"answer_indexes":{"type":"array","items":{"type":"integer"},"nullable":true,"description":"Indexes into `choices` matching the patient's answer (choice-based types)."},"external_id":{"type":"string","nullable":true,"description":"External-system identifier for this question."},"variable_name":{"type":"string","nullable":true,"description":"Internal variable name used by the script."},"default_value":{"type":"string","nullable":true,"description":"Default value for the question."},"display_value":{"type":"string","nullable":true,"description":"Human-friendly display value."},"prompt_question":{"type":"string","nullable":true,"description":"LLM-facing prompt used to elicit the answer."},"notes":{"type":"string","nullable":true,"description":"Free-text notes."},"hide_from_summary_display":{"type":"boolean","description":"Always false for items present in this payload (true items are filtered out)."}}}},"follow_up_items":{"type":"array","items":{"type":"string"},"description":"Free-text follow-up actions identified during the call."},"kickout_summaries":{"type":"array","description":"Clinical escalations triggered during the call.","items":{"type":"object","properties":{"display_name":{"type":"string","description":"Human-readable escalation name."},"kickout_id":{"type":"string","description":"Stable identifier for the escalation rule that fired."},"severity":{"type":"string","nullable":true,"description":"Triage color. `in_progress` indicates a kickout that has started but not yet been color-classified.","enum":["in_progress","white","blue","green","yellow","amber","orange","purple","red"]},"summary":{"type":"string","nullable":true,"description":"Generated summary of the escalation context."},"utp_status":{"type":"string","nullable":true,"description":"Patient transfer status for this kickout (if applicable)."}}}},"form_fill_summaries":{"type":"array","description":"Structured form responses captured during the call (raw format — `output_value` is not unpacked).","items":{"type":"object","properties":{"question_id":{"type":"string","description":"Stable identifier for the form question."},"output_value":{"type":"object","description":"Schema varies by form type. Listed subfields are guidance, not contract. Common keys: `question`, `answer`, `options`, `question_type`, `answer_indices`, `external_id`, `external_options`, `formatted_options`, `changed`, `applicable`, `skipped`, `asked`, `should_highlight`, `arbitration_status`.","additionalProperties":true},"created_by_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Internal user ID that captured this form answer."},"sort_order":{"type":"integer","description":"Display order index (0-based)."}}}},"schedule_engine_summaries":{"type":"array","description":"Appointment scheduling outputs produced during the call.","items":{"type":"object","properties":{"output_name":{"type":"string","description":"Output identifier. Default \"scheduling_summary\"."},"output_type":{"type":"string","description":"Engine that produced the output.","enum":["ehr_summary","interjection","notes","mcm_summary","offline_errors","kickout","scheduling","form_fill","mdr_detection","adverse_event_detection","call_errors","escalation_reconciliation","audio_summary","ai_screener_detected","custom_call_success","analytics"]},"output_value":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Shape varies by scheduling tool. New keys may appear with new integrations."}}}}}},"todos_summary":{"type":"array","description":"Task items (todos) generated from the call. Note: key name is `todos_summary` (singular `summary`), not `todo_summaries`.","items":{"type":"object","properties":{"todo_id":{"type":"string","format":"uuid"},"partner_id":{"type":"string","format":"uuid"},"action":{"type":"string","description":"Action to be taken."},"due_date":{"type":"string","format":"date-time","description":"ISO-8601 UTC due date."},"completed_date":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601 UTC completion timestamp; null when not completed."},"priority":{"type":"string","description":"Todo priority.","enum":["urgent","high","medium","low"]},"todo_status":{"type":"string","description":"Todo lifecycle status.","enum":["draft","pending","completed","archived"]},"todo_type":{"type":"string","description":"Todo category.","enum":["unknown","patient_escalation","patient_escalation_failure","patient_call_review","patient_callback","clinical_review","client_follow_up","escalation_case_review","data_annotation"]},"todo_metadata":{"type":"object","nullable":true,"additionalProperties":true,"description":"Free-form, varies by `todo_type`. Not stable."},"external_id":{"type":"string","nullable":true,"description":"External-system identifier for this todo."}}}},"pdf_summary":{"type":"string","format":"byte","nullable":true,"description":"Base64-encoded PDF rendering of the call summary. May be null if PDF generation failed."},"html_summary":{"type":"string","description":"HTML rendering of the call summary."},"txt_summary":{"type":"string","description":"Plain-text rendering of the call summary."}}},"example":{"call":{"call_id":"3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","call_type":"telephone","call_status":"call_completed","call_direction":"outbound","encounter_id":"11111111-2222-3333-4444-555555555555","initiated_by_patient":false,"call_purpose":"Medication refill reminder","created_at":"2025-08-20T23:35:00+00:00","started_at":"2025-08-20T23:38:00+00:00","ended_at":"2025-08-20T23:41:52+00:00","call_channel":"twilio","created_by_user_id":"00000000-0000-0000-0000-000000000000","duration":232.0,"call_host_url_base":"https://host.us.hippocraticai.com","call_end_reason":"user_ended_call_regular","language":"en","phone_number":null,"telephony_sid":"CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","telephony_account_sid":"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","telephony_provider":"twilio","customer_patient_id":"XX0101506","dispositions":[{"call_disposition_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","call_id":"3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","created_by_user_id":"00000000-0000-0000-0000-000000000000","disposition":"call_hung_up","call_outcome":"no_action","custom_call_success_evaluation_status":"evaluated","custom_call_success":true,"created_at":"2025-08-20T23:41:52+00:00"}]},"json_summary":{"call_id":"3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","patient_name":"Smith, John","date_of_birth":"1937-04-22","datetime_of_call":"2025-08-20 07:38 PM EDT","physician_name":"","call_purpose":"Medication refill reminder","conversation_summary":"Patient reports they have filled their Simvastatin and Metformin prescriptions...","call_disposition":"call_hung_up","mrn":"XX0101506","gender":"male","phone_number":"+15125551212","care_location_name":"Test Location","call_url":"https://portal.us.hippocraticai.com/call/3b13f7a1-39aa-4a1a-8419-20e42c5b3f9b","call_type":"preop_ortho","do_not_call":false,"custom_variables":{},"medication_summaries":[{"name":"Simvastatin","type":"Old Rx","dosage":"20 mg daily","adherence":"Yes","notes":""}],"device_summaries":[],"summary_question_answers":[],"follow_up_items":[],"kickout_summaries":[],"form_fill_summaries":[],"schedule_engine_summaries":[]},"todos_summary":[],"pdf_summary":"JVBERi0xLjQKJ...","html_summary":"<html>...</html>","txt_summary":"Call Summary\n..."}}}},"responses":{"200":{"description":"Webhook received and processed successfully"},"201":{"description":"Webhook received and call summary created"},"400":{"description":"Bad request - invalid payload format"},"401":{"description":"Unauthorized - invalid webhook authentication"},"500":{"description":"Internal server error processing webhook"}},"security":[{"webhookAuth":[]}]}}}}