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
- A patient books. Your system calls
POST /v1/appointments with
the appointment time and the patient's phone number.
- We talk to the patient. VisitConfirmed reaches out from your
practice's number, confirms the visit, sends reminders, and answers
questions.
- 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.
- 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:
400: the request failed validation. The body has type, title
and status, plus errors, which maps each rejected field to a
list of messages.
403: the API key is missing or invalid, or a test key was used
against production (or a live key against the sandbox). The body
is {"detail": "..."}.
404: the resource doesn't exist 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 (see below).
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