Categorizing appointments logically and accurately is one of the most important parts of building a dental or medical app. This month, we’ve got tips for how to do that using appointment_descriptors and appointment_types. 

We’re also excited to share the latest Synchronizer API enhancements, including improvements to how we detect canceled appointments. Check out the details below!

API spotlight: Categorizing appointments

Dental and medical apps often need to insert specific data into a health record system or trigger distinct notifications based on appointment details — such as what procedures are included, whether it’s a new or existing patient, and if there is insurance involved.  

Rather than designing a unique workflow for every possible combination of appointment details, it’s often easier to group similar appointments together into categories that require related pre-appointment reminders, forms, billing notifications, or scheduling parameters. 

The Synchronizer API has two ways to categorize appointments: appointment_descriptors and appointment_types. These let you group appointments according to procedure codes, EHR-specific appointment types, or your own custom categories.

Appointment_descriptors: Work with EHR-specific appointment types and procedure codes

{
    "code": true,
    "description": [],
    "error": [],
    "data": [
        {
            "id": 2581,
            "descriptor_type": "Procedure Codes",
            "name": "Composite-2 Surf, Posterior",
            "code": "T5833",
            "location_id": 405,
            "foreign_id": "10:1",
            "foreign_id_type": "msg-opendental-DataSource-156",
            "data": {
                "AbbrDesc": "C2(P)",
                "ProcTime": "/X/",
                "PaintType": 6,
                "TreatArea": 1
            },
            "active": true,
            "last_sync_time": null,
            "created_at": "2022-04-19T22:57:22.860Z",
            "updated_at": "2022-04-19T22:57:22.860Z"
        },
        {
            "id": 1822,
            "descriptor_type": "Appointment Type",
            "name": "NEW PRIMARY CARE VISIT",
            "code": "NPR",
            "location_id": 5,
            "foreign_id": "17",
            "foreign_id_type": "msg-athena-DataSource-2558",
            "data": {},
            "active": true,
            "last_sync_time": null,
            "created_at": "2022-04-19T22:57:22.860Z",
            "updated_at": "2022-04-19T22:57:22.860Z"
        }
      ]
}

Appointment_descriptors store emr_appt_descriptor_ids, which represent various ways that appointments are categorized or labeled within health record systems. For example, you can retrieve Current Dental Terminology (CDT) codes, Current Procedural Terminology (CPT) codes, and EHR-specific appointment types.

CDT and CPT codes (known collectively as procedure codes) are industry standard ways of representing procedures and services that are associated with an appointment. Consider mapping these codes to appointments in your app if you want to trigger billing notifications after each procedure.

You can also use appointment_descriptors to identify EHR-specific appointment types that reflect how practices have grouped appointments into higher-level categories within their health record systems. This can be useful if you want to let practices send notifications or let patients schedule appointments based on those categories.

You can retrieve appointment_descriptors for a given location by making a Get request to /locations/{id}/appointment_descriptors as shown below:

curl --request GET \
     --url https://nexhealth.info/locations/YOUR_LOCATION/appointment_descriptors \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

If instead you want to see the specific procedure codes or EHR-specific appointment types attached to an appointment and patient, you can do that by adding "include[]=descriptors" to a Get request to /appointments as shown below:

curl --request GET \
     --url 'https://nexhealth.info/appointments/YOUR_APPOINTMENT_ID?subdomain=YOUR_SUBDOMAIN&include\[\]=descriptors' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Appointment_types: Work with your own custom appointment categories

curl --request POST \
     --url 'https://nexhealth.info/appointment_types?subdomain=YOUR_SUBDOMAIN' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "appointment_type": {
          "emr_appt_descriptor_ids": [
               123456,
               123457,
               123458
          ],
          "name": "Cleaning",
          "minutes": 60,
          "parent_type": "Institution"
     }
}

The appointment_types endpoint stores NexHealth Appointment Types, which can be logical bundles of dental CDT codes, medical CPT codes, or EHR-specific appointment types.

Unlike appointment_descriptors, which reflect how appointments are categorized or labeled in a health record system, NexHealth Appointment Types are fully customizable and let you group appointments however you would like in your application.

NexHealth Appointment Types can also be used in conjunction with appointment_descriptors. Simply map your NexHealth Appointment Types to  emr_appt_descriptor_ids, as shown above, and you can read or write the underlying CDT codes, CPT codes, or EHR-specific appointment types that correspond with the custom groupings you’ve created.

Synchronizer API product updates

Dentrix Ascend

• We’ve upgraded the Synchronizer to detect appointment cancellations more reliably so you can avoid sending erroneous reminders. When appointment cancellations are detected, the cancelled field on the appointments object will equal true.

Eaglesoft

• We now recognize unscheduled status for appointments in Eaglesoft and return those appointments as canceled. This makes it easier to support Eaglesoft practices that send appointments to an unscheduled queue to reschedule. Unscheduled appointments will have cancelled=true, helping you to avoid sending reminders and other pre-appointment messages to those patients until they’re rescheduled.

eClinicalWorks

• We’ve improved form insertion rates so that POST requests to the forms endpoint will succeed more reliably for eClinicalWorks.