VisitConfirmed API

More of the patients who book with you show up. VisitConfirmed reaches every patient you book, confirms the visit, answers their questions, and catches cancellations and reschedules early enough for you to fill the slot. Patients who need a person go straight to your staff, before the appointment rather than after a no-show.

Your practice's voice, not ours. Patients hear from your practice by two-way text and phone. Every message goes out under your practice's name from a phone number dedicated to your practice.

A small integration. Your system sends us each booking in one request, tells us when a booking is cancelled or moved, and receives what each patient decided as a signed webhook. There is nothing to poll. Getting started walks through it in the sandbox, end to end.

Which integration do you need?

You use an EHR or scheduling platform we already connect to. You don't need this API. We connect directly to Healthie, Canvas, Medplum and Tellescope, and to Elation, athenahealth and others through Keragon, with no engineering work on your side. See our integrations.

You built your own booking system. This API is for you. Your developers send us each booking and receive each patient's decision by webhook, so your system stays the source of truth. The rest of this page shows how, starting with Getting started.

You want patients rebooked straight into your calendar. Out of the box, when a patient asks for a different time we send your system an appointment.reschedule_requested event and you move the booking. If your system has an API for availability and booking, we can connect to it so the agent offers open slots and rebooks the patient itself. Ask us at support@visitconfirmed.com.

How an integration works

  1. A patient books. Your system calls POST /v1/appointments with the appointment time and the patient's phone number.
  2. We talk to the patient. VisitConfirmed reaches out from your practice's number, confirms the visit, sends reminders, and answers questions.
  3. We tell you the outcome. Each result arrives at your webhook endpoint as a signed event: the patient confirmed, declined, asked for a different time, stopped responding, or needs a person.
  4. You tell us about changes. When an appointment is cancelled or moved in your system, call POST /v1/appointments/{appointment_id}/cancel or POST /v1/appointments/{appointment_id}/reschedule so the conversation with the patient stays accurate.

Getting started

This walkthrough runs entirely in the sandbox, where nothing reaches patients, and ends with a webhook arriving at your endpoint.

1. Get your sandbox key. Request sandbox keys and we'll set up a sandbox copy of your practice and send you a vc_test_ key. Your vc_live_ production key follows when you're ready to go live. Export the test key so the examples below work as written:

export VISITCONFIRMED_TEST_KEY=vc_test_...

2. Subscribe a staging endpoint. Register an HTTPS URL that can receive events. Sandbox webhooks are delivered for real, so use a staging server or a request inspector, not production.

curl https://visitconfirmed.com/v1/webhooks \
  -H "Authorization: Bearer $VISITCONFIRMED_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://staging.example.com/webhooks/visitconfirmed",
    "events": [
      "appointment.confirmed",
      "appointment.declined",
      "appointment.reschedule_requested",
      "appointment.escalated"
    ],
    "label": "Staging"
  }'

The response includes the signing secret. It is shown only once, so store it now:

{
  "id": "c0ffee00-2222-4c00-8000-000000000003",
  "url": "https://staging.example.com/webhooks/visitconfirmed",
  "events": [
    "appointment.confirmed",
    "appointment.declined",
    "appointment.reschedule_requested",
    "appointment.escalated"
  ],
  "label": "Staging",
  "is_active": true,
  "created_at": "2026-12-01T09:00:00.000000+00:00",
  "secret": "whsec_8jKqv1x9aBcDeFg2hIjLmNoPqRsTuVwX"
}

3. Send an appointment. In your integration, send each booking as soon as it is made. Include your own booking ID as external_id so a retried request is never processed twice.

curl https://visitconfirmed.com/v1/appointments \
  -H "Authorization: Bearer $VISITCONFIRMED_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "booking_48213",
    "scheduled_at": "2026-12-03T10:30:00+00:00",
    "appointment_type": "Initial consultation",
    "provider_name": "Dr. Okafor",
    "modality": "virtual",
    "workflow": "confirm",
    "contact": {
      "external_id": "patient_9921",
      "first_name": "Amelia",
      "last_name": "Hughes",
      "phone_e164": "+447700900123",
      "email": "amelia@example.com"
    }
  }'

The response confirms the conversation has started. Store appointment_id: it is how webhooks refer to this booking, and you need it to cancel or reschedule.

{
  "status": "processed",
  "engagement_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "contact_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "appointment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contact_created": true
}

If the patient has already opted out, you still get 201, but with status: "declined_opted_out" and no appointment_id. Nobody contacts the patient and no webhook follows, so update the booking in your system from this response rather than waiting for an event.

4. Force an outcome. In production the patient decides. In the sandbox you can decide for them, using the engagement_id from step 3:

curl https://visitconfirmed.com/v1/sandbox/engagements/1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed/resolve \
  -H "Authorization: Bearer $VISITCONFIRMED_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "confirmed"}'

5. Receive the webhook. Your staging endpoint receives a signed POST. Match it to the booking by data.appointment.id, the appointment_id you stored in step 3, and act on event_type:

{
  "event_type": "appointment.confirmed",
  "event_id": "evt_9f8c2d4a0000400080000000000000a1",
  "occurred_at": "2026-12-02T11:14:08.123456+00:00",
  "organization_id": "9b2ffadd-1111-4b00-8000-000000000002",
  "data": {
    "appointment": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "scheduled",
      "scheduled_at": "2026-12-03T10:30:00+00:00",
      "appointment_type": "Initial consultation"
    },
    "contact": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "phone_e164": "+447700900123",
      "opted_out": false
    }
  }
}

A forced outcome changes only the conversation, so data.appointment.status stays scheduled here. When a real patient confirms in production it reads confirmed. Either way, branch on event_type.

Verify the signature (see Webhooks), respond with any 2xx, and update the booking. To exercise your other handlers, repeat steps 3 and 4 with a new external_id for each of declined and escalated: both end the conversation, so it can't be given another outcome afterwards. When an appointment.reschedule_requested event arrives, book the new time on your side and call reschedule.

6. Keep us in sync. Whenever a booking is cancelled or moved on your side, call cancel or reschedule with its appointment_id.

7. Go live. Swap in your vc_live_ key and register your production endpoint with it. Subscriptions belong to one environment, so the staging subscription keeps receiving sandbox events only.

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer vc_live_...

Each key belongs to one practice and acts only on that practice's data. A missing or invalid key returns 403. Keep keys on your server; never put one in a web page or mobile app.

Two exceptions apply only to POST /v1/leads, for web form tools that can't set headers: it accepts a lead-capture key, which opens that one operation and nothing else, and that key may be passed in the URL as ?api_key=. Full-access keys are refused in the URL.

Testing in the sandbox

Your vc_test_ key points at a sandbox copy of your practice. It behaves like production with one difference: nothing reaches patients. Texts, emails and calendar invites are suppressed, so you can test with realistic data. Webhooks are delivered for real, so point your sandbox subscription at a staging endpoint.

To test outcome handling without waiting for a patient, force a conversation's outcome with POST /v1/sandbox/engagements/{engagement_id}/resolve, as in step 4 of Getting started. The matching webhook fires as it would in production. Test and live keys can't cross over: a vc_test_ key is refused in production and a vc_live_ key in the sandbox, and the resolve endpoint refuses production keys.

Webhooks

Outcomes are pushed to you, so you never need to poll. Each event is a POST with a JSON body (see the event reference below) and a VisitConfirmed-Signature header.

Delivery. Respond with any 2xx within 10 seconds. If you don't, we retry with exponential backoff, waiting about 1 minute, then 2, then 4, doubling up to an hour between attempts, for up to 10 attempts over roughly four hours. A 4xx response other than 408 or 429 is treated as a permanent rejection and is not retried. We don't follow redirects, so give us the final URL.

At least once. An event can arrive more than once. Use event_id to ignore duplicates.

Verifying signatures

The header looks like this:

VisitConfirmed-Signature: t=1715692800,v1=41a68cc88b00374653f3540575684d633e647a33af0143e59ea4ef8adbffc548

v1 is a hex HMAC-SHA256 of the string "{t}.{raw request body}", keyed with your subscription's signing secret. Compute it over the raw body exactly as received, before any JSON parsing, compare it in constant time, and reject events whose t is more than 5 minutes from your clock.

Python:

import hashlib
import hmac
import time


def is_valid_visitconfirmed_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(parts["t"])
    if abs(time.time() - timestamp) > 300:
        return False
    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Node.js:

const crypto = require("crypto");

function isValidVisitConfirmedSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
  const timestamp = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return (
    expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  );
}

Identifiers and idempotency

IDs we issue (appointment_id, contact_id, engagement_id, webhook subscription IDs) are UUIDs. Webhook event_id values are evt_ followed by 32 hex characters.

external_id is your own ID for the booking. Sending one makes POST /v1/appointments idempotent: the first request for an external_id is processed, and any later request with the same external_id returns 200 with status: "duplicate" and changes nothing, even if other fields differ. To move an appointment, use reschedule; to stop one, use cancel. A request without an external_id is never deduplicated, so always send one.

cancel and reschedule are safe to retry: cancelling an appointment that is already cancelled, or moving it to the time it already has, returns its current state and changes nothing.

Phone numbers and time zones

Send phone numbers in international E.164 format: a +, the country code, then the number with no spaces, such as +447700900123 (UK) or +15555550101 (US).

Every scheduled_at must include a time zone offset, such as 2026-12-03T10:30:00+00:00 for 10:30 in London in winter, 2026-06-03T10:30:00+01:00 for 10:30 in London in summer, or a UTC time ending in Z. A time without an offset is rejected with 400. Messages to patients show the time in the patient's time zone where we know it, and otherwise in your practice's time zone, which we set during onboarding. Times in webhook payloads are in UTC.

Errors

Errors return JSON with a standard HTTP status:

Rate limits

Each API key can make up to 300 requests a minute; lead-capture keys are limited to 30 a minute. Requests over the limit return 429 with a Retry-After header giving the seconds to wait.

Versioning

The URL carries the major version (/v1). Changes within a version only add things: new optional fields, new event types, new endpoints. Your integration should ignore fields and event types it doesn't recognize. Breaking changes ship as a new major version, with notice and time to migrate.

Appointments

Send appointments, keep them in sync, and look up their outcome.

Find an appointment by your external_id

GET /v1/appointments

Returns the appointment you sent with this external_id. Use it if you didn't keep the appointment_id from the create response. Because external_id is unique within your practice, the result holds at most one appointment.

Parameters

external_id (query, required)

Your ID for the appointment, as sent on create.

Responses

200

The matching appointment in a one-item array, or an empty array if there is none.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Send an appointment for confirmation

POST /v1/appointments

Sends one appointment, with the patient's contact details, and starts the confirmation conversation. The response returns immediately; the patient's decision arrives later by webhook.

Store the appointment_id from the response. You need it to cancel or reschedule the appointment.

If the patient has previously opted out of messages, the appointment is accepted but nobody contacts the patient, and the response says so with status: "declined_opted_out". No webhook follows in that case.

Request body

external_id (string)

Your ID for this appointment. Makes the request idempotent (see Identifiers and idempotency). Always send one.

scheduled_at (string, required)

Appointment start time in ISO 8601, with a time zone offset. A time without an offset is rejected with 400.

appointment_type (string)

What kind of visit this is, as patients should hear it, for example "Initial consultation".

provider_name (string)

The clinician's name as patients should hear it.

modality (one of: in_person, virtual)

How the patient attends. virtual covers video and phone visits: patients are never given directions to an office. in_person visits use location_name, or your practice's address if you leave it out.

location_name (string)

Where an in-person visit happens, as patients should hear it.

workflow (one of: confirm, remind)
  • confirm: ask the patient to confirm, and handle their reply.
  • remind: send reminders without asking for a confirmation. The patient can still reply and we still answer.
contact (ContactInline, required)

The patient this appointment is for.

contact.external_id (string)

Your ID for this patient.

contact.first_name (string)
contact.last_name (string)
contact.phone_e164 (string, required)

Phone number in international E.164 format, for example +447700900123 or +15555550101.

contact.email (string)

Responses

200

Duplicate. An appointment with this external_id was already sent for your practice, so nothing changed.

201

Accepted. status is processed when the conversation with the patient has started, or declined_opted_out when the patient has opted out and won't be contacted.

400

The request failed validation. errors maps each rejected field to a list of messages; for the nested contact object it is a nested object.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Get an appointment

GET /v1/appointments/{appointment_id}

Returns the appointment's current state, including the conversation's outcome once there is one.

Parameters

appointment_id (path, required)

The appointment_id returned when you created the appointment.

Responses

200

Current state of the appointment.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Cancel an appointment

POST /v1/appointments/{appointment_id}/cancel

Call this when the appointment is cancelled in your system. We stop the conversation and send the patient no further messages about it.

Safe to retry: cancelling an appointment that is already cancelled, or whose conversation has already finished, returns its current state and changes nothing.

Parameters

appointment_id (path, required)

The appointment_id returned when you created the appointment.

Request body

reason (string)

A note for your records. Never shown to the patient.

Responses

200

Cancelled, or already finished.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Move an appointment to a new time

POST /v1/appointments/{appointment_id}/reschedule

Call this when the appointment moves in your system, including after you book a new time in response to an appointment.reschedule_requested event. We let the patient know the new time and confirm it with them, and the outcome arrives by webhook as usual.

Safe to retry: moving an appointment to the time it already has returns its current state and changes nothing.

Parameters

appointment_id (path, required)

The appointment_id returned when you created the appointment.

Request body

scheduled_at (string, required)

The new start time, with a time zone offset.

provider_name (string)
location_name (string)

Responses

200

New time accepted. The conversation reopens to confirm the new time, so outcome is null until the patient answers.

400

The request failed validation. errors maps each rejected field to a list of messages; for the nested contact object it is a nested object.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

409

The change conflicts with the appointment's current state, for example rescheduling an appointment that was already cancelled.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Contacts

Read a patient's consent state and record opt-outs your staff capture.

Get a patient's consent state

GET /v1/contacts/{contact_id}

Parameters

contact_id (path, required)

Responses

200

The contact.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Record an opt-out your staff captured

POST /v1/contacts/{contact_id}/opt-out

Use this when a patient asks your practice directly (in person, by phone, or in your own system) to stop receiving messages. We stop contacting them, and future appointments for them return declined_opted_out. You don't need to call this when a patient replies STOP to one of our messages; we record that ourselves and send a contact.opted_out event.

Parameters

contact_id (path, required)

Request body

reason (string)
source (one of: phone, in_person, ehr, other)

Where your staff captured the opt-out.

Responses

200

Opt-out recorded.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Webhooks

Manage the endpoints that receive outcome events.

List your webhook subscriptions

GET /v1/webhooks

Responses

200

Your subscriptions.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Subscribe an endpoint to outcome events

POST /v1/webhooks

The URL must use HTTPS and be reachable from the public internet. The signing secret is returned only in this response, so store it immediately. You can't retrieve it later.

Request body

url (string, required)

Must use HTTPS and be reachable from the public internet.

events (array, required)
label (string)

Responses

201

Subscription created.

400

The request failed validation. errors maps each rejected field to a list of messages; for the nested contact object it is a nested object.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Remove a webhook subscription

DELETE /v1/webhooks/{webhook_id}

Deliveries to this endpoint stop immediately, including retries of earlier events.

Parameters

webhook_id (path, required)

Responses

204

Subscription removed.

403

The API key is missing, malformed or invalid, or it was used in the wrong environment (a vc_test_ key against production, or a vc_live_ key against the sandbox).

404

No such resource for your practice.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Leads

Send new patient inquiries from your web forms. VisitConfirmed replies to the person and works toward booking a first visit.

Reachability check for the lead URL

GET /v1/leads

Some form tools fetch a webhook URL before they will save it. This answers that check with 200 and needs no key. It reads no data and records nothing; sending a lead still requires a key. HEAD behaves the same way.

Responses

200

The endpoint is reachable.

Send a new patient inquiry

POST /v1/leads

Send a submission from one of your web forms, in whatever shape the form produces: any JSON object, or form-encoded fields (repeated keys, such as a multi-select, are kept as a list). We store it as received and reply 201 straight away, then contact the person in the background. If the form shows they agreed to be texted, VisitConfirmed replies to them; otherwise the inquiry goes to your staff to follow up. With a vc_test_ key the submission is stored and nothing else happens. Because the 201 never depends on that follow-up, you don't need to retry. A body we can't parse is still stored, and its 400 response includes the lead_submission_id. A form tool that can't set an Authorization header may put a lead-capture key in the URL as ?api_key=. Never put a key in a form field, because form fields are visible in the page.

Responses

201

Submission stored.

400

The body couldn't be parsed, or wasn't an object. The submission is stored anyway and the response includes its lead_submission_id.

403

A missing or invalid API key.

413

The submission is too large. A form submission should be a page of answers, not a document.

429

Too many requests. Wait the number of seconds in Retry-After, then retry.

Testing (sandbox)

Helpers for testing your integration with a vc_test_ key. They refuse production keys.

Force an outcome in the sandbox

POST /v1/sandbox/engagements/{engagement_id}/resolve

Sandbox only. Moves a test appointment's conversation straight to an outcome so you can test your webhook handling without a patient. The matching appointment.confirmed, appointment.declined or appointment.escalated event fires as it would in production. Requesting the outcome the conversation already has returns 200 and changes nothing. Production keys get 403.

Parameters

engagement_id (path, required)

The engagement_id returned when you created the appointment.

Request body

outcome (one of: confirmed, declined, escalated, required)

Responses

200

Outcome applied, or already in place.

400

Missing or invalid outcome.

403

Either the API key is missing or invalid ({detail} body), or the key belongs to production rather than the sandbox ({type, title, status} body).

404

No conversation with this ID for your practice.

409

The conversation already has a different final outcome, or can't move to the requested one from its current state.

Webhook events

The patient confirmed the appointment.

Event appointment.confirmed, sent as a POST to your webhook URL.

The conversation is finished.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

The patient declined the appointment or asked to cancel it.

Event appointment.declined, sent as a POST to your webhook URL.

The conversation is finished and the appointment is cancelled. Cancel the booking in your system, and the slot is free to offer to someone else. A patient who had already opted out before you sent the appointment doesn't produce this event; that case is answered in the POST /v1/appointments response instead.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

The patient asked for a different time.

Event appointment.reschedule_requested, sent as a POST to your webhook URL.

The appointment still stands until you change it. Book a new time in your system, then call POST /v1/appointments/{appointment_id}/reschedule and we confirm the new time with the patient. If you can't offer a new time, call cancel.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

The patient needs a person.

Event appointment.escalated, sent as a POST to your webhook URL.

The conversation is finished. Something came up that needs your staff, such as a question the agent shouldn't answer or a request it can't complete. Someone from your practice should contact the patient. The appointment itself is unchanged.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

The appointment time passed without a decision from the patient.

Event appointment.expired, sent as a POST to your webhook URL.

The conversation is finished. The patient never confirmed or declined.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

The patient opted out of messages.

Event contact.opted_out, sent as a POST to your webhook URL.

The patient replied STOP or otherwise asked not to be contacted. We won't message them again, and future appointments for them return declined_opted_out. data.appointment is the most recent appointment, or null if the opt-out happened outside a conversation about one, as in this example.

Parameters

VisitConfirmed-Signature (header, required)

t=<unix_seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret>. Reject deliveries whose t is more than 5 minutes from your clock.

Request body

event_type (one of: appointment.confirmed, appointment.declined, appointment.reschedule_requested, appointment.escalated, appointment.expired, contact.opted_out, required)
event_id (string, required)

Unique per event. Use it to ignore duplicate deliveries.

occurred_at (string, required)
organization_id (string, required)

Your practice's ID.

data (object, required)
data.appointment (WebhookAppointment or null, required)

The appointment the event is about. The key is always present, but its value is null when the event isn't tied to an appointment, for example an escalated new patient inquiry or an opt-out outside a conversation about a visit. Check for null before reading it.

data.contact (WebhookContact, required)

The patient an event is about.

Responses

2XX

Acknowledged.

Download the OpenAPI specification