Adding Appointments to Zus
In-House Appointments
In-house appointments—those scheduled directly between your organization and the patient—can be added to Zus via EHR integration or directly using the FHIR API.
When you write in-house (or "first party") appointments to Zus, we automatically refresh the patient’s chart 48–72 hours before the scheduled visit. This ensures your care team has the most up-to-date clinical data available for comprehensive chart preparation.
Required fields:
- Appointment.status - must be “pending” or “booked” in order to trigger a refresh. Updating this status to “canceled” will also cancel the refresh.
- Appointment.start - necessary to schedule the refresh. Updating the date on an appointment resource will also reschedule the follow up refresh.
- It is also recommended to include Location.address for optimal request targeting.
Specialist Referrals
You can also utilize Zus to follow up on referral appointments with a third party.
To register a new specialist appointment, submit a bundle to https://api.zusapi.com/fhir/ that includes a subject patient, a location, and an appointment resource. The “ifNoneExist” attribute enables conditional writes to reference an existing Patient or Location resource based on the identifier value and system provided (see below).
Required fields:
- Appointment.meta.tag - by default, Zus is set up to automatically refresh patient data before the appointments that you write to Zus (for chart prep). Adding a meta.tag with system “https://zusapi.com/refreshType” and code “Specialist Appointment” informs Zus to instead refresh shortly after the appointment date (typically within 48 hours) to capture visit documentation.
- Appointment.status - must be “pending” or “booked” in order to trigger a refresh. Updating this status to “canceled” will also cancel the refresh.
- Appointment.start - necessary to schedule the refresh. Updating the date on an appointment resource will also reschedule the follow up refresh.
- It is also recommended to include Location.address for optimal request targeting
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000001",
"request": {
"method": "POST",
"url": "Patient",
"ifNoneExist": "identifier={{PATIENT IDENTIFIER SYSTEM}}|{{PATIENT IDENTIFIER VALUE}}"
},
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "{{PATIENT IDENTIFIER SYSTEM}}",
"value": "{{PATIENT IDENTIFIER VALUE}}"
}
],
"name": [
{
"family": "Zhang",
"given": [
"Bruno"
]
}
],
"telecom": [
{
"system": "phone",
"value": "555-460-1718",
"use": "home"
}
],
"gender": "male",
"birthDate": "1972-04-18",
"address": [
{
"line": [
"376 SHADOW LN"
],
"city": "LAS VEGAS",
"state": "NV",
"postalCode": "89106"
}
]
}
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000002",
"request": {
"method": "POST",
"url": "Location",
"ifNoneExist": "identifier={{LOCATION IDENTIFIER SYSTEM}}|{{LOCATION IDENTIFIER VALUE}}"
},
"resource": {
"resourceType": "Location",
"identifier": [
{
"system": "{{LOCATION IDENTIFIER SYSTEM}}",
"value": "{{LOCATION IDENTIFIER VALUE}}"
}
],
"name": "Sample Health Associates, P.C.",
"address": {
"use": "work",
"type": "physical",
"line": ["123 Main St"],
"city": "Chicago",
"state": "IL",
"postalCode": "60601",
"country": "US"
},
},
},
{
"fullUrl": "urn:uuid:00000000-0000-0000-0000-000000000003",
"request": {
"method": "POST",
"url": "Appointment"
},
"resource": {
"resourceType": "Appointment",
"meta" : {
"tag" : [
{
"system" : "https://zusapi.com/refreshType",
"code" : "Specialist Appointment"
}
]
},
"identifier": [
{
"system": "https://elationemr.com/appointment-id",
"value": "5432123"
}
],
"status": "booked",
"start": "2024-08-21T14:00:00.000Z",
"end": "2024-08-21T15:45:00.000Z",
"participant": [
{
"actor": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000001",
"type": "Patient"
},
"required": "required",
"status": "accepted"
},
{
"actor": {
"reference": "urn:uuid:00000000-0000-0000-0000-000000000002",
"type": "Location"
},
"required": "required",
"status": "accepted"
}
]
}
}
]
}
Tips for conditional writes in Zus:
- Use a POST if you want to link to existing resources without updating them, using the ifNoneExist field in the bundle's request to provide the identifier to match.
- Use a PUT if you want your request to update existing resources with new information, using an identifier query param to provide the identifier to match.
- When setting up fullURL UUIDs, remember:
- You need a unique UUID for each resource in the bundle, but you can reuse UUIDs across different bundles.
- The UUIDs need to be structurally valid, but can be completely arbitrary; the Zus system will replace them with real generated IDs.
- Make sure the identifier you use in the ifNoneExist parameter or the identifier search parameter matches the identifier in the resource itself.
- If the resource does not exist, it will get created with only the information you supply in the API call. If you expect that this request might write Patients or Practitioners for the first time, make sure the stub has sufficient identifying information.
- If there are multiple copies of a resource with the same identifier belonging to your organization, your conditional write will fail. If you expect that to be a regular occurrence, we recommend just using a standard (not conditional) POST or PUT.
Updated 1 day ago