Guides

Read and write procedure codes

Read the codes on an appointment, and attach them when you book.

This guide shows how to read and write procedure codes and system-specific appointment types. Procedure codes are Current Dental Terminology (CDT) codes for dental and Current Procedural Terminology (CPT) codes for medical. System-specific appointment types are another way that health record systems such as athenahealth categorize appointments.

You need a sandbox and a bearer token. If you do not have a sandbox, sign up. If you do not have a bearer token, see Authentication.

The samples use the values from the Quickstart: NEX_TOKEN, NEX_SUBDOMAIN, NEX_LOCATION_ID, NEX_PATIENT_ID, NEX_PROVIDER_ID, NEX_OPERATORY_ID and NEX_APPOINTMENT_ID. Node samples need Node 18 or later, saved as .mjs files. Python samples need the requests package.

Reading procedure codes and system-specific appointment types

Procedure codes and system-specific appointment types show how a health record system categorizes an appointment and which services go with it. Use them to show the value of the appointments you book for the practice. They can also trigger pre-op or post-op instructions, or help you evaluate and recommend care options.

They are available for a location or for an appointment. To list every procedure code and system-specific appointment type in a location, send a GET request to /locations/{id}/appointment_descriptors.

curl -s --request GET \
  --url "https://nexhealth.info/locations/$NEX_LOCATION_ID/appointment_descriptors" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN"
const { NEX_TOKEN, NEX_LOCATION_ID } = process.env;

const url = `https://nexhealth.info/locations/${NEX_LOCATION_ID}/appointment_descriptors`;

const res = await fetch(url, {
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
  },
});
console.log(await res.json());
import os

import requests

res = requests.get(
    "https://nexhealth.info/locations/" + os.environ["NEX_LOCATION_ID"] + "/appointment_descriptors",
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
)
print(res.json())

The response looks like this. The procedure code or system-specific appointment type is in code. A display name is in name.

{
    "code": true,
    "description": null,
    "error": null,
    "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"
        }
      ]
}

To see the procedure codes or system-specific appointment types on one appointment, send a GET request to /appointments/{id}/appointment_descriptors or /appointments/{id}?include[]=descriptors.

curl -s --globoff --request GET \
  --url "https://nexhealth.info/appointments/$NEX_APPOINTMENT_ID?subdomain=$NEX_SUBDOMAIN&include[]=descriptors" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN"
const { NEX_APPOINTMENT_ID, NEX_TOKEN, NEX_SUBDOMAIN } = process.env;

const url = `https://nexhealth.info/appointments/${NEX_APPOINTMENT_ID}?subdomain=${NEX_SUBDOMAIN}&include[]=descriptors`;

const res = await fetch(url, {
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
  },
});
console.log(await res.json());
import os

import requests

res = requests.get(
    "https://nexhealth.info/appointments/" + os.environ["NEX_APPOINTMENT_ID"],
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
        "include[]": "descriptors",
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
)
print(res.json())

The appointment in the response has a descriptors property. It holds the procedure codes and system-specific appointment types for the appointment.

"descriptors": [
      {
            "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"
        }
    ]

Writing procedure codes and system-specific appointment types

Write procedure codes and system-specific appointment types so the appointments you book carry what the practice needs. The practice can see which services to provide and can bill insurance correctly.

To do this, set up a NexHealth appointment type and link it to the procedure codes or system-specific appointment types you want to send. A NexHealth appointment type is different from a system-specific appointment type. It is something like a cleaning or an extraction. Think of it as a bundle of procedure codes or system-specific appointment types that stands for one kind of appointment.

To create a NexHealth appointment type, send a POST request to /appointment_types, as shown below. The emr_appt_descriptor_ids field sets which procedure codes and system-specific appointment types go with this type of appointment.

Fill in the details of the NexHealth appointment type and its emr_appt_descriptor_ids. These IDs cover the ways health record systems categorize appointments, such as CDT codes, CPT codes and system-specific appointment types.

curl -s --request POST \
  --url "https://nexhealth.info/appointment_types?subdomain=$NEX_SUBDOMAIN" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "appointment_type": {
      "emr_appt_descriptor_ids": [123456, 123457, 123458],
      "name": "Cleaning",
      "minutes": 60,
      "parent_type": "Institution"
    }
  }'
const { NEX_TOKEN, NEX_SUBDOMAIN } = process.env;

const url = `https://nexhealth.info/appointment_types?subdomain=${NEX_SUBDOMAIN}`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    appointment_type: {
      emr_appt_descriptor_ids: [123456, 123457, 123458],
      name: "Cleaning",
      minutes: 60,
      parent_type: "Institution",
    },
  }),
});
console.log(await res.json());
import os

import requests

res = requests.post(
    "https://nexhealth.info/appointment_types",
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
    json={
        "appointment_type": {
            "emr_appt_descriptor_ids": [123456, 123457, 123458],
            "name": "Cleaning",
            "minutes": 60,
            "parent_type": "Institution",
        },
    },
)
print(res.json())

If you already have a NexHealth appointment type, edit it with the request below to add the procedure codes and system-specific appointment types.

Set NEX_APPT_TYPE_ID to the ID of the NexHealth appointment type. Fill in the emr_appt_descriptor_ids to attach.

curl -s --request PATCH \
  --url "https://nexhealth.info/appointment_types/$NEX_APPT_TYPE_ID?subdomain=$NEX_SUBDOMAIN" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "appointment_type": { "emr_appt_descriptor_ids": [1234545, 123453] } }'
const { NEX_APPT_TYPE_ID, NEX_TOKEN, NEX_SUBDOMAIN } = process.env;

const url = `https://nexhealth.info/appointment_types/${NEX_APPT_TYPE_ID}?subdomain=${NEX_SUBDOMAIN}`;

const res = await fetch(url, {
  method: "PATCH",
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    appointment_type: {
      emr_appt_descriptor_ids: [1234545, 123453],
    },
  }),
});
console.log(await res.json());
import os

import requests

res = requests.patch(
    "https://nexhealth.info/appointment_types/" + os.environ["NEX_APPT_TYPE_ID"],
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
    json={
        "appointment_type": {
            "emr_appt_descriptor_ids": [1234545, 123453],
        },
    },
)
print(res.json())

Once the NexHealth appointment type exists, set it when you create an appointment. The procedure codes and system-specific appointment types are then attached to the appointment.

Set it with the appointment_type_id property.

The sample reads the NexHealth appointment type from NEX_APPT_TYPE_ID. Fill in the start time. If you are not sure how to create an appointment, see the Quickstart.

cat > appointment-request.json <<EOF
{
  "appt": {
    "patient_id": $NEX_PATIENT_ID,
    "provider_id": $NEX_PROVIDER_ID,
    "operatory_id": $NEX_OPERATORY_ID,
    "start_time": "2026-12-01T16:00:00Z",
    "appointment_type_id": $NEX_APPT_TYPE_ID
  }
}
EOF

curl -s --request POST \
  --url "https://nexhealth.info/appointments?subdomain=$NEX_SUBDOMAIN&location_id=$NEX_LOCATION_ID" \
  --header "Nex-Api-Version: v3.0.0" \
  --header "Authorization: Bearer $NEX_TOKEN" \
  --header "Content-Type: application/json" \
  --data @appointment-request.json
const { NEX_APPT_TYPE_ID, NEX_TOKEN, NEX_SUBDOMAIN, NEX_LOCATION_ID, NEX_PROVIDER_ID, NEX_PATIENT_ID, NEX_OPERATORY_ID } = process.env;

const url = `https://nexhealth.info/appointments?subdomain=${NEX_SUBDOMAIN}&location_id=${NEX_LOCATION_ID}`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Nex-Api-Version": "v3.0.0",
    Authorization: `Bearer ${NEX_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    appt: {
      patient_id: Number(NEX_PATIENT_ID),
      provider_id: Number(NEX_PROVIDER_ID),
      operatory_id: Number(NEX_OPERATORY_ID),
      start_time: "2026-12-01T16:00:00Z",
      appointment_type_id: Number(NEX_APPT_TYPE_ID),
    },
  }),
});
console.log(await res.json());
import os

import requests

res = requests.post(
    "https://nexhealth.info/appointments",
    params={
        "subdomain": os.environ["NEX_SUBDOMAIN"],
        "location_id": os.environ["NEX_LOCATION_ID"],
    },
    headers={
        "Nex-Api-Version": "v3.0.0",
        "Authorization": "Bearer " + os.environ["NEX_TOKEN"],
    },
    json={
        "appt": {
            "patient_id": int(os.environ["NEX_PATIENT_ID"]),
            "provider_id": int(os.environ["NEX_PROVIDER_ID"]),
            "operatory_id": int(os.environ["NEX_OPERATORY_ID"]),
            "start_time": "2026-12-01T16:00:00Z",
            "appointment_type_id": int(os.environ["NEX_APPT_TYPE_ID"]),
        },
    },
)
print(res.json())

Updated 6 days ago

What’s Next

What to check when no slots come back.

Did this page help you?
ChangelogMCP serverErrorsdevelopers@nexhealth.com