Skip to content

Appointment Management ​

Manage appointments within your client organization.

Authentication ​

Requires a Client token with scopes:

  • appointment:read — For GET endpoints
  • appointment:write — For POST/PUT/DELETE endpoints

Endpoints ​

List Appointments ​

http
GET /ext/latest/appointments
Authorization: Bearer {token}

Query Parameters:

  • limit (optional) — Page size (default: 10, max: 100)
  • offset (optional) — Page offset (default: 0)

Response:

json
{
  "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 ​

http
GET /ext/latest/appointments/{appointmentId}
Authorization: Bearer {token}

Response:

json
{
  "data": { ... }
}

Create Appointment ​

http
POST /ext/latest/appointments
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

json
{
  "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):

json
{
  "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 ​

http
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.

json
{
  "patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
  "targetDate": "2026-04-20",
  "description": "Rescheduled follow-up"
}

Updating an appointment does not trigger an HIE query.

Response:

json
{
  "data": { ... }
}

Delete Appointment ​

http
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:

  1. appointmentId, if you send one.
  2. Otherwise externalId + patientId, if you send an externalId.
  3. Otherwise patientId + targetDate, compared as a calendar date, among appointments that have no externalId.

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.

http
POST /ext/latest/appointments/batch
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

json
{
  "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:

json
{
  "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 }
}
  • status per item is created, updated, or error.
  • Partial success is supported — one bad item does not fail the whole batch.
  • The top-level autoQuery object reports the aggregate dispatch result across all created appointments.
  • Only items that come back created can start a records query. Items that come back updated never query again.
  • Returns 400 for more than 100 items or an empty appointments array.

Appointment Object Fields ​

FieldTypeCreateUpdateDescription
appointmentIdstring——System-generated UUID (read-only)
clientIdstring——Owning client ID (read-only, derived from token)
patientIdstringrequiredrequiredPatient UUID
targetDatestringrequiredrequiredTarget date for the appointment (YYYY-MM-DD)
descriptionstringoptionaloptionalAppointment description
externalIdstringoptional—External system identifier for the appointment (nullable)
autoQuerybooleanoptional—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.
providerNpistringoptional—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/appointments
  • POST /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/medications or GET /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:

http
POST /ext/latest/appointments
Content-Type: application/json
Authorization: Bearer {token}
json
{
  "patientId": "c7836b96-5de1-4f86-a6ea-04edd578490a",
  "targetDate": "2026-10-01",
  "description": "Point-of-need records pull",
  "autoQuery": true,
  "providerNpi": "1234567890"
}

Response (201 Created):

json
{
  "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.created event, 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}/files
    • GET /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 targetDate can 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) targetDate still starts a query.
  • autoQuery: true on the request forces a query regardless of the client-level autoQueryOnNewAppt setting.
  • autoQuery: false suppresses the query regardless of the client-level setting — use this to opt out of a retrieval for a specific appointment.
  • When autoQuery is omitted entirely, the client's autoQueryOnNewAppt setting is used as the default.
  • A query needs an NPI. The API uses providerNpi from 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:

FieldTypeDescription
skippedintegerCreated appointments that didn't get a query
queuedintegerAuto-query messages successfully enqueued. Each query runs asynchronously after the response.
failedintegerAuto-query messages that failed to enqueue
failuresarrayDetails for each message that failed to enqueue. Empty when failed is 0.
reasonstringWhy 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 seeWhy
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 0The query message didn't make it onto the queue. The appointment still exists. To retry, post a new appointment.

Examples ​

Node.js ​

javascript
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 ​

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 ​

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid fields
401FORBIDDENMissing authentication or invalid token
403FORBIDDENInsufficient scopes
404RESOURCE_NOT_FOUNDAppointment not found
422INVALID_REFERENCEReferenced patient does not exist

Vivlio Health API Documentation