---
updatedAt: 2026-05-27T07:44:11.000Z
agentTools:
  projectIndex: https://docs.nexhealth.com/llms.txt
---

# View appointments

This endpoint returns the appointments starting within the requested time window, narrowed down by the optional filters configured. At least one of location_id or foreign_id must be provided.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "NexHealth API v3.0.0 (Default)",
    "description": "v3.0.0 and v20240412 are two names for the same API version; the Nex-Api-Version header accepts either value. This is the current default API version.\n\nWelcome to the developer hub and documentation for NexHealth API. This section of guide describes the operations, response parameters, request parameters, and parameter constraints related to User API. The term Operations refer to functions or methods. The operations are included in requests and send to the web server. Each operation performs a different action or a query on database.",
    "termsOfService": "https://www.nexhealth.com/terms-of-service",
    "contact": {
      "name": "NexHealth",
      "email": "info@nexhealth.com"
    },
    "license": {
      "name": "NexHealth License 1.0",
      "url": "https://www.nexhealth.com/privacy"
    },
    "version": "v20240412"
  },
  "security": [
    {
      "Authorization": []
    }
  ],
  "tags": [
    {
      "name": "Appointments",
      "description": "A booking on the Practice's calendar"
    }
  ],
  "paths": {
    "/appointments": {
      "get": {
        "summary": "View appointments",
        "description": "This endpoint returns the appointments starting within the requested time window, narrowed down by the optional filters configured. At least one of location_id or foreign_id must be provided.",
        "parameters": [
          {
            "in": "header",
            "name": "Nex-Api-Version",
            "description": "The NexHealth API version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v3.0.0"
            }
          },
          {
            "in": "query",
            "name": "subdomain",
            "description": "Used to scope the request to the specified institution",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "location_id",
            "description": "Used to scope the request to the specified location",
            "required": false,
            "example": 1,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "sort",
            "description": "Optional comma-separated string of fields to sort on.\nInclude a leading dash for descending order.\n\nAvailable fields:\n  * updated_at\n  * -updated_at\n",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "start",
            "description": "A parseable date string defining the earliest returned records. Recommended format is YYYY-MM-DDThh:mm:ss+0000",
            "required": true,
            "example": "2024-04-01T00:00:00Z",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "end",
            "description": "A parseable date string defining the last returned records. Recommended format is YYYY-MM-DDThh:mm:ss+0000",
            "required": true,
            "example": "2024-04-30T23:59:59Z",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "timezone",
            "description": "Timezone for the appointment clinic",
            "required": false,
            "example": "America/New_York",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cancelled",
            "description": "Filter by cancelled status.",
            "required": false,
            "example": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "unavailable",
            "description": "Unavailable appointments are used to block availability on a schedule, specify to set the filter",
            "required": false,
            "example": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "nex_only",
            "description": "Only show appointments booked via NexHealth API",
            "required": false,
            "example": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "updated_since",
            "description": "Query appointments whose records have updated since the specified datetime in ISO8601 format. Must be a parseable date/time, recommended formats are YYYY-MM-DD or YYYY-MM-DDT00:00:00+0000",
            "required": false,
            "example": "2024-04-12T10:30:00Z",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "appointment_type_id",
            "description": "Get appointments for a specific appointment type",
            "required": false,
            "example": 27,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "foreign_id",
            "description": "Unique appointment id from the EHR",
            "required": false,
            "example": "94",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "created_by",
            "description": "Query appointments that were created by a specific user",
            "required": false,
            "example": 197,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "start_cursor",
            "description": "First item of the current page. Starts empty",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "end_cursor",
            "description": "Last item of the current page. Starts empty",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "per_page",
            "description": "Number of results to return per page. Maximum allowed amount is 1000.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 5
            }
          },
          {
            "in": "query",
            "name": "patient_ids[]",
            "description": "Get appointments for specific patients (up to 25 ids)",
            "required": false,
            "example": [
              2897
            ],
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "in": "query",
            "name": "provider_ids[]",
            "description": "Query appointments that are booked with the specified providers only",
            "required": false,
            "example": [
              104
            ],
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "in": "query",
            "name": "operatory_ids[]",
            "description": "Query appointments that are booked in the specified operatories only",
            "required": false,
            "example": [
              181
            ],
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_V2_Entities_AppointmentWithoutIncludes_Collection_Response_WithCursor"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Forbidden"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_NotFound"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_InternalServerError"
                }
              }
            }
          }
        },
        "tags": [
          "Appointments"
        ],
        "operationId": "getAppointments"
      }
    }
  },
  "servers": [
    {
      "url": "https://nexhealth.info"
    }
  ],
  "components": {
    "securitySchemes": {
      "Authorization": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    },
    "schemas": {
      "API_Errors_BadRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_BadRequest model"
      },
      "API_Errors_Unauthorized": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_Unauthorized model"
      },
      "API_Errors_Forbidden": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_Forbidden model"
      },
      "API_Errors_InternalServerError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_InternalServerError model"
      },
      "API_Errors_NotFound": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "description": "Indicates the success or failure of the request."
          },
          "description": {
            "type": "string",
            "description": "Additional context about the request to help with debugging."
          },
          "data": {
            "type": "object"
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Any errors that occured during the execution of the request."
          }
        },
        "description": "API_Errors_NotFound model"
      },
      "API_V2_Entities_AppointmentWithoutIncludes": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "example": 1822,
            "description": "Appointment id"
          },
          "patient_id": {
            "type": "integer",
            "format": "int32",
            "example": 2897,
            "description": "Appointment patient id",
            "nullable": true
          },
          "provider_id": {
            "type": "integer",
            "format": "int32",
            "example": 104,
            "description": "Provider id",
            "nullable": true
          },
          "provider_name": {
            "type": "string",
            "example": "Dr. John Smith",
            "description": "Provider name",
            "nullable": true
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Appointment scheduled start time in UTC"
          },
          "confirmed": {
            "type": "boolean",
            "example": true,
            "description": "Appointment confirmation status",
            "nullable": true
          },
          "patient_missed": {
            "type": "boolean",
            "example": false,
            "description": "Did the patient no show? Not supported by all integrations",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Appointment created time in UTC"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Appointment last updation time in UTC"
          },
          "note": {
            "type": "string",
            "example": "Patient has been having a cough for 3 days",
            "description": "Appointment note",
            "nullable": true
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Appointment scheduled end time in UTC"
          },
          "unavailable": {
            "type": "boolean",
            "example": false,
            "description": "Is this appointment a scheduling block (blocks off the schedule)",
            "nullable": true
          },
          "cancelled": {
            "type": "boolean",
            "example": false,
            "description": "Is this appointment cancelled?"
          },
          "timezone": {
            "type": "string",
            "example": "America/New_York",
            "description": "Appointment timezone"
          },
          "institution_id": {
            "type": "integer",
            "format": "int32",
            "example": 1,
            "description": "Institution id"
          },
          "appointment_type_id": {
            "type": "integer",
            "format": "int32",
            "example": 27,
            "description": "Nexhealth appointment_type id, 0 if not set",
            "nullable": true
          },
          "checkin_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Time the patient checked in at in UTC. Not supported by all integrations",
            "nullable": true
          },
          "location_id": {
            "type": "integer",
            "format": "int32",
            "example": 1,
            "description": "Appointment location id",
            "nullable": true
          },
          "foreign_id": {
            "type": "string",
            "example": "94",
            "description": "Identifier NexHealth uses to uniquely match this record to its counterpart in the integrated EHR. How it is derived differs between EHRs and may change; treat it as an opaque string and do not parse it.",
            "nullable": true
          },
          "foreign_id_type": {
            "type": "string",
            "example": "msg-dentrix-DataSource-100",
            "description": "Unique identifier for the integrated system itself"
          },
          "misc": {
            "type": "object",
            "example": {
              "is_booked_on_nexhealth": true
            },
            "description": "Miscellaneous information for the appointment. The is_booked_on_nexhealth key indicates whether the appointment was booked through NexHealth",
            "nullable": true
          },
          "last_sync_time": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Last Sync time in UTC",
            "nullable": true
          },
          "patient_confirmed": {
            "type": "boolean",
            "example": false,
            "description": "Is this appointment confirmed by the patient (as opposed to the office)?",
            "nullable": true
          },
          "created_by_user_id": {
            "type": "integer",
            "format": "int32",
            "example": 197,
            "description": "Id of the user who booked the appointment",
            "nullable": true
          },
          "is_guardian": {
            "type": "boolean",
            "example": false,
            "description": "Was the appointment booked by a guardian?",
            "nullable": true
          },
          "patient_confirmed_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Time of patient_confirmation in UTC",
            "nullable": true
          },
          "cancelled_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Time of appointment cancellation in UTC. Note this will not be reset if the appointment is uncancelled",
            "nullable": true
          },
          "is_new_clients_patient": {
            "type": "boolean",
            "example": false,
            "description": "Is this a new patient at this practice?",
            "nullable": true
          },
          "confirmed_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Time of appointment confirmation by the office in UTC",
            "nullable": true
          },
          "sooner_if_possible": {
            "type": "boolean",
            "example": false,
            "description": "Does patient want an earlier time?",
            "nullable": true
          },
          "operatory_id": {
            "type": "integer",
            "format": "int64",
            "example": 181,
            "description": "Operatory id for the appointment",
            "nullable": true
          },
          "checked_out": {
            "type": "boolean",
            "example": false,
            "description": "Has the patient checked out? Not supported by all integrations",
            "nullable": true
          },
          "checked_out_at": {
            "type": "string",
            "format": "date-time",
            "example": "2020-06-05T20:16:57.007Z",
            "description": "Time of check out in UTC",
            "nullable": true
          },
          "referrer": {
            "type": "string",
            "example": "http://mypractice.com/book",
            "description": "Optional field to store URI origin of the booking",
            "nullable": true
          },
          "is_past_patient": {
            "type": "boolean",
            "example": true,
            "description": "Does this patient have prior appointments?",
            "nullable": true
          },
          "timezone_offset": {
            "type": "string",
            "example": "-4:00",
            "description": "Timezone offset string"
          }
        }
      },
      "API_V2_Entities_AppointmentWithoutIncludes_Collection_Response_WithCursor": {
        "type": "object",
        "properties": {
          "code": {
            "type": "boolean",
            "example": false,
            "description": "Indicates the success or failure of the request"
          },
          "description": {
            "type": "string",
            "example": "Description",
            "description": "Additional context on the request to help with debugging."
          },
          "error": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Error message"
            ],
            "description": "Any errors that occur during the execution of the request."
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/API_V2_Entities_AppointmentWithoutIncludes"
            }
          },
          "page_info": {
            "type": "object",
            "example": {
              "has_previous_page": false,
              "has_next_page": false,
              "start_cursor": "AAAAA",
              "end_cursor": "BBBBBB"
            },
            "description": "Pagination information that can be used for fetching previous and next pages."
          }
        },
        "description": "API_V2_Entities_AppointmentWithoutIncludes_Collection_Response_WithCursor model"
      }
    }
  }
}
```

# Sibling pages

* [View appointment](https://docs.nexhealth.com/reference/getappointmentsid.md)
* [Edit Appointment](https://docs.nexhealth.com/reference/patchappointmentsid.md)
* [View appointment descriptors](https://docs.nexhealth.com/reference/getappointmentsidappointmentdescriptors.md)
* [Create appointment](https://docs.nexhealth.com/reference/postappointments.md)