---
updatedAt: 2026-10-01T07:05:39.000Z
agentTools:
  projectIndex: https://docs.nexhealth.com/v2.2.2/llms.txt
---

# View appointment slots

This endpoint returns available appointment slots for the given providers at the given locations over the specified date range.

> 🚧 Use smaller number of days for better performance
>
> Response time increases when requesting a large number of days. For better performance, request a smaller number of days and leverage the `next_available_date` field if no slots are found.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "NexHealth API v2.2.2 (Deprecated)",
    "description": "> **⚠️ Deprecated.** v2.2.2 is the legacy version of the NexHealth API and is deprecated; new development should target v3.0.0 (also known by its original date-based name v20240412). Our migration guide walks through every breaking change: https://docs.nexhealth.com/v20240412/docs/api-v2-to-v20240412-migration-guide\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": "v2"
  },
  "security": [
    {
      "Authorization": []
    }
  ],
  "tags": [
    {
      "name": "Appointment Slots",
      "description": "Valid start date/times for an appointment"
    }
  ],
  "paths": {
    "/appointment_slots": {
      "get": {
        "summary": "View appointment slots",
        "description": "This endpoint returns available appointment slots for the given providers at the given locations over the specified date range.",
        "parameters": [
          {
            "in": "header",
            "name": "Nex-Api-Version",
            "description": "The NexHealth API version",
            "required": true,
            "schema": {
              "type": "string",
              "default": "v2"
            }
          },
          {
            "in": "query",
            "name": "subdomain",
            "description": "Used to scope the request to the specified institution",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "start_date",
            "description": "Date string you want results to start at, format YYYY-MM-DD",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "in": "query",
            "name": "days",
            "description": "Number of days to include, counting the start date. For best performance, this value should not exceed 14 days.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "appointment_type_id",
            "description": "Specify an appointment type to filter returned slots and set slot_length to appointment_type.minutes",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "slot_length",
            "description": "Manually specify slot length in minutes. Defaults to 15 minutes",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "slot_interval",
            "description": "Manually specify the time in minutes between returned slot start times when a contiguous opening exists longer than the slot_length",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "in": "query",
            "name": "overlapping_operatory_slots",
            "description": "Return all available slots for operatories at a given time instead of returning only the first found. Default is false",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "in": "query",
            "name": "lids[]",
            "description": "Array of Location Ids",
            "required": true,
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "in": "query",
            "name": "pids[]",
            "description": "Array of Provider Ids",
            "required": true,
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          },
          {
            "in": "query",
            "name": "operatory_ids[]",
            "description": "Specify this if booking is mapped to operatory in this location",
            "required": false,
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "format": "int32"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Entities_AvailableSlotResponse_Collection_Response"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_Forbidden"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/vnd.Nexhealth+json;version=2": {
                "schema": {
                  "$ref": "#/components/schemas/API_Errors_InternalServerError"
                }
              }
            }
          }
        },
        "tags": [
          "Appointment Slots"
        ],
        "operationId": "getAppointmentSlots"
      }
    }
  },
  "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_Entities_AvailableSlotResponse_Collection_Response": {
        "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_Entities_AvailableSlotResponse"
            }
          },
          "count": {
            "type": "integer",
            "format": "int32",
            "example": 2,
            "description": "Number of total objects, in case of collection."
          }
        },
        "description": "API_Entities_AvailableSlotResponse_Collection_Response model"
      },
      "API_Entities_AvailableSlotResponse": {
        "type": "object",
        "properties": {
          "lid": {
            "type": "integer",
            "format": "int32",
            "example": 1,
            "description": "Relevant location id"
          },
          "pid": {
            "type": "integer",
            "format": "int32",
            "example": 83,
            "description": "Relevant providers id. Omitted when slots are not grouped by provider",
            "nullable": true
          },
          "operatory_id": {
            "type": "integer",
            "format": "int64",
            "example": 54,
            "description": "Relevant operatory id. Omitted when slots are not grouped by operatory",
            "nullable": true
          },
          "slots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/API_Entities_AvailableSlot"
            },
            "description": "Array of available start times"
          },
          "next_available_date": {
            "type": "string",
            "format": "date",
            "example": "2022-11-17",
            "description": "The earliest date when a valid slot exists",
            "nullable": true
          }
        }
      },
      "API_Entities_AvailableSlot": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "example": "2017-10-09T07:00:00.000-04:00",
            "description": "Start time of the slot in the practices timezone"
          },
          "end_time": {
            "type": "string",
            "example": "2017-10-09T07:30:00.000-04:00",
            "description": "End time of the slot in the practices timezone"
          },
          "operatory_id": {
            "type": "integer",
            "format": "int64",
            "example": 54,
            "description": "Operatory id for the slot. Omitted when the slot is not tied to an operatory"
          },
          "provider_id": {
            "type": "integer",
            "format": "int32",
            "example": 83,
            "description": "Provider id for the slot, if available. Omitted when the slot is not tied to provider"
          }
        }
      }
    }
  }
}
```