Appointment Management
Manage appointments within your client organization.
Authentication
Requires a Client token with scopes:
appointment:read— For GET endpointsappointment:write— For POST/PUT/DELETE endpoints
Endpoints
List Appointments
GET /ext/latest/appointments
Authorization: Bearer {token}Query Parameters:
limit(optional) — Page size (default: 10, max: 100)offset(optional) — Page offset (default: 0)
Response:
{
"data": [
{
"appointmentId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-15",
"description": "Follow-up visit",
"externalId": null
}
],
"limit": 10,
"offset": 0,
"hasMore": true
}Get Appointment
GET /ext/latest/appointments/{appointmentId}
Authorization: Bearer {token}Response:
{
"data": { ... }
}Create Appointment
POST /ext/latest/appointments
Content-Type: application/json
Authorization: Bearer {token}Request Body:
{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-15",
"description": "Follow-up visit",
"externalId": "EXT-APPT-001",
"autoQuery": true,
"providerNpi": "1234567890"
}Response (201 Created):
{
"data": {
"appointmentId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-15",
"description": "Follow-up visit",
"externalId": null
},
"autoQuery": { "skipped": 0, "queued": 1, "failed": 0 },
"message": "Appointment created"
}The top-level autoQuery object reports whether an HIE auto-query was dispatched for this appointment (see HIE Auto-Query below).
TIP
Creating an appointment is how you start a records query for a patient. See Starting a Records Query.
Update Appointment
PUT /ext/latest/appointments/{appointmentId}
Content-Type: application/json
Authorization: Bearer {token}Request Body: patientId and targetDate are required. Send description to change it. Fields you leave out keep their stored values, and the appointment's externalId does not change.
{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-20",
"description": "Rescheduled follow-up"
}Updating an appointment does not trigger an HIE query.
Response:
{
"data": { ... }
}Delete Appointment
DELETE /ext/latest/appointments/{appointmentId}
Authorization: Bearer {token}Response (204 No Content): (no body)
Batch Upsert Appointments
Upsert up to 100 appointments in a single call. Each item is matched to an existing appointment in your client, in this order:
appointmentId, if you send one.- Otherwise
externalId+patientId, if you send anexternalId. - Otherwise
patientId+targetDate, compared as a calendar date, among appointments that have noexternalId.
A matched appointment is updated, and fields you leave out keep their stored values. An item with no match creates a new appointment.
To reschedule, send the same externalId and patientId with the new targetDate. The existing appointment is updated, keeps its appointmentId, and no HIE query is triggered. If more than one appointment matches, the most recently created one is updated.
POST /ext/latest/appointments/batch
Content-Type: application/json
Authorization: Bearer {token}Request Body:
{
"appointments": [
{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-15",
"externalId": "EXT-APPT-001",
"autoQuery": true,
"providerNpi": "1234567890"
},
{
"patientId": "8b2e1d94-0000-0000-0000-000000000000",
"targetDate": "2026-04-16"
}
]
}Response:
{
"data": [
{
"status": "created",
"sourceIndex": 0,
"externalId": "EXT-APPT-001",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-04-15",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"appointmentId": "019d0716-6a88-70af-9ef4-50c1cc2bda86"
}
],
"summary": { "total": 2, "created": 2, "updated": 0, "error": 0 },
"autoQuery": { "skipped": 0, "queued": 2, "failed": 0 }
}statusper item iscreated,updated, orerror.- Partial success is supported — one bad item does not fail the whole batch.
- The top-level
autoQueryobject reports the aggregate dispatch result across all created appointments. - Only items that come back
createdcan start a records query. Items that come backupdatednever query again. - Returns 400 for more than 100 items or an empty
appointmentsarray.
Appointment Object Fields
| Field | Type | Create | Update | Description |
|---|---|---|---|---|
appointmentId | string | — | — | System-generated UUID (read-only) |
clientId | string | — | — | Owning client ID (read-only, derived from token) |
patientId | string | required | required | Patient UUID |
targetDate | string | required | required | Target date for the appointment (YYYY-MM-DD) |
description | string | optional | optional | Appointment description |
externalId | string | optional | — | External system identifier for the appointment (nullable) |
autoQuery | boolean | optional | — | Controls whether an HIE auto-query fires on creation. true forces a query; false suppresses it. Both override the client's autoQueryOnNewAppt setting. When omitted, the client setting is used. Has no effect on updates. |
providerNpi | string | optional | — | Provider NPI for routing the HIE auto-query. Falls back to the client's group NPI if omitted. |
Starting a Records Query
The API has no call that fetches a patient's records on demand. You start a records query by creating an appointment for the patient.
Calls that start a query:
POST /ext/latest/appointmentsPOST /ext/latest/appointments/batch
Calls that never start a query:
PUT /ext/latest/appointments/{appointmentId}POST /ext/latest/patients- Every records or files read, such as
GET /ext/latest/patients/{patientId}/records/medicationsorGET /ext/latest/patients/{patientId}/files
A query starts only for a newly created appointment. A batch item that comes back with status: "updated" doesn't query again, and neither does any PUT.
Each POST /ext/latest/appointments creates a new appointment, even when the body is the same as an earlier one. If you post the same appointment twice, you get two appointments and two queries.
Whether a new appointment actually queues a query depends on the rules in HIE Auto-Query below.
Fetching records at the point of need
To pull records for a patient you're seeing today, create an appointment with today's date as the targetDate, autoQuery: true, and the provider's NPI:
POST /ext/latest/appointments
Content-Type: application/json
Authorization: Bearer {token}{
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-10-01",
"description": "Point-of-need records pull",
"autoQuery": true,
"providerNpi": "1234567890"
}Response (201 Created):
{
"data": {
"appointmentId": "019d0716-6a88-70af-9ef4-50c1cc2bda86",
"clientId": "a587f055-12ff-4009-a4b2-6300f665f35e",
"patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
"targetDate": "2026-10-01",
"description": "Point-of-need records pull",
"externalId": null
},
"autoQuery": { "skipped": 0, "queued": 1, "failed": 0 },
"message": "Appointment created"
}queued: 1 means the query is waiting to run. The query runs asynchronously after the API returns the 201. We don't publish a completion time for queries.
Knowing when records are ready
The appointment has no query-status field, so the API can't tell you whether a query has finished. How you find out depends on your account:
- Partner accounts with an enabled webhook receive a
parsed-data.createdevent, but only when the query finds at least one new file. A query that finds nothing new sends no webhook. See Webhooks. - Accounts with no partner don't receive webhooks today. Poll these two calls and watch
total:GET /ext/latest/patients/{patientId}/filesGET /ext/latest/patients/{patientId}/records/medications?limit=1
When total goes up, new records have arrived. If total never changes, the query is either still running or found nothing new, and the API can't tell you which.
HIE Auto-Query
When an appointment is created, the API can automatically trigger an HIE (Health Information Exchange) query to pull the patient's latest records.
- Auto-query fires only on creation, not on updates.
- The appointment's
targetDatecan be no more than the client's lookahead days from today (default 14 days). There is no earliest date: a same-day or past (backdated)targetDatestill starts a query. autoQuery: trueon the request forces a query regardless of the client-levelautoQueryOnNewApptsetting.autoQuery: falsesuppresses the query regardless of the client-level setting — use this to opt out of a retrieval for a specific appointment.- When
autoQueryis omitted entirely, the client'sautoQueryOnNewApptsetting is used as the default. - A query needs an NPI. The API uses
providerNpifrom the request, then the provider on the appointment, then the client's group NPI.
Vivlio Health sets the lookahead window and the autoQueryOnNewAppt setting for your account. You can't change either one through the API. To change them, contact your Vivlio Health representative.
autoQuery response fields:
| Field | Type | Description |
|---|---|---|
skipped | integer | Created appointments that didn't get a query |
queued | integer | Auto-query messages successfully enqueued. Each query runs asynchronously after the response. |
failed | integer | Auto-query messages that failed to enqueue |
failures | array | Details for each message that failed to enqueue. Empty when failed is 0. |
reason | string | Why nothing was queued. Present only when nothing was queued. failed and failures are left out when reason is present. |
When a query isn't queued:
| What you see | Why |
|---|---|
reason: "auto_query_disabled" | The request sent autoQuery: false; or autoQuery was left out and the client's autoQueryOnNewAppt setting is off; or the targetDate is past the lookahead window; or the targetDate doesn't parse as a date. All four return this same reason. |
reason: "no_valid_query_payloads" | No NPI was found. The request had no providerNpi, the appointment has no provider, and the client has no group NPI. |
reason: "no_created_workflows" | Every item in a batch matched an existing appointment and came back updated, so there was nothing new to query. |
reason: "client_not_found" or "missing_start_query_queue" | A configuration problem on Vivlio Health's side. Contact your Vivlio Health representative. |
failed greater than 0 | The query message didn't make it onto the queue. The appointment still exists. To retry, post a new appointment. |
Examples
Node.js
async function createAppointment(token, patientId, targetDate) {
const response = await fetch('https://api.vivliohealth.io/ext/latest/appointments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`
},
body: JSON.stringify({
patientId,
targetDate,
description: 'Routine checkup'
})
});
return response.json();
}Python
import requests
def create_appointment(token, patient_id, target_date):
response = requests.post(
'https://api.vivliohealth.io/ext/latest/appointments',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
},
json={
'patientId': patient_id,
'targetDate': target_date,
'description': 'Routine checkup'
}
)
response.raise_for_status()
return response.json()Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid fields |
| 401 | FORBIDDEN | Missing authentication or invalid token |
| 403 | FORBIDDEN | Insufficient scopes |
| 404 | RESOURCE_NOT_FOUND | Appointment not found |
| 422 | INVALID_REFERENCE | Referenced patient does not exist |
