# Public API – Appointment Management

Operations related to patients, appointments, providers and so on.

Version: 193.0.0

## Servers

Sandbox
```
https://test.hs1api.com/ascend-gateway/api
```

Prod
```
https://prod.hs1api.com/ascend-gateway/api
```

## Security

### bearerAuth

Type: http
Scheme: bearer
Bearer Format: JWT

### oAuthSandbox

OAuth 2.0 client credentials (Sandbox)

Type: oauth2
Token URL: https://test.hs1api.com/oauth/client_credential/accesstoken?grant_type=client_credentials
Scopes:

## Download OpenAPI description

 - [Public API – Appointment Management](https://papidocs.hs1api.com/_bundle/PublicAPI/api-appointment-management.yaml)

 - [GET /v1/appointmentcolors](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentcolorsv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [GET /v1/appointmentcolors/{appointmentColorId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentcolorsbyappointmentcoloridv1.md): Returns the AppointmentColor (V1) identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/appointmentcolors/{appointmentColorId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putappointmentcolorsbyappointmentcoloridv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [GET /v1/appointmenthistories](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmenthistoriesv1.md): **Query shape:** Prefer a **narrow** filter. Required filter keys must be supplied where documented below. A very wide date range with no other scoping can **408** (timeout) on large tenants; retry wi
 - [GET /v1/appointmenthistories/{appointmentHistoryId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmenthistoriesbyappointmenthistoryidv1.md): Returns the AppointmentHistoryV1 identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [GET /v1/appointmentstatushistories](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentstatushistoriesv1.md): **Query shape:** Prefer a **narrow** filter. Required filter keys must be supplied where documented below. A very wide date range with no other scoping can **408** (timeout) on large tenants; retry wi
 - [GET /v1/appointmentstatushistories/{appointmentStatusHistoryId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentstatushistoriesbyappointmentstatushistoryidv1.md): Returns the AppointmentStatusHistoryV1 identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [GET /v1/appointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentsv1.md): **Query shape:** Prefer a **narrow** filter—combine `patient.id`, `provider.id`, or `location.id` with `lastModified` or date bounds where possible. A very wide date range with no other scoping can **
 - [POST /v1/appointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postappointmentsv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/appointments/async](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentsasyncv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [GET /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmentsbyappointmentidv1.md): Returns the appointment identified by the path parameter. **404** when the appointment is missing or not accessible in the organization context.
 - [PUT /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putappointmentsbyappointmentidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deleteappointmentsbyappointmentidv1.md): Permanently deletes the appointment and cascades related tasks, history, and recare links. **404** when the resource is missing or already deleted.
 - [GET /v1/appointmenttasks](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmenttasksv1.md): **Query shape:** Prefer a **narrow** filter—combine `appointment.id` or `id` with other scoping keys where possible. A very wide query with no scoping can **408** (timeout) on large tenants; retry wit
 - [POST /v1/appointmenttasks](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postappointmenttasksv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getappointmenttasksbyappointmenttaskidv1.md): Returns the AppointmentTaskV1 identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putappointmenttasksbyappointmenttaskidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deleteappointmenttasksbyappointmenttaskidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
 - [POST /v1/events](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/createevent.md): Creates a new event. Supports recurring events with weekly or monthly patterns.
 - [GET /v1/events](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getallevents.md): Retrieves events based on filter criteria. Supports pagination and various filtering options.
 - [GET /v1/events/async](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getalleventsasync.md): Retrieves events asynchronously. Returns the first 10 results immediately and delivers matching records via StreamAPI webhooks (SNS). Filter remaining results with MessageAttributes.RoutingKey.
 - [GET /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/geteventbyid.md): Retrieves a specific event by its ID. Returns detailed event information including location, operatory, and recurrence settings if applicable.
 - [PUT /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/updateevent.md): Updates an existing event. Supports updating single occurrences or entire recurring series based on the recurrenceTarget parameter.
 - [DELETE /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deleteevent.md): Deletes an event by its ID. For recurring events, you can specify whether to delete the entire series or just a single occurrence using the recurrenceTarget parameter.
 - [GET /v1/missedappointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getmissedappointmentsv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [GET /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getmissedappointmentsbymissedappointmentidv1.md): Returns the missed appointment identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putmissedappointmentsbymissedappointmentidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deletemissedappointmentsbymissedappointmentidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
 - [GET /v1/patientbookingavailabilities](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getpatientbookingavailabilitiesv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [POST /v1/patientbookingavailabilities](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postpatientbookingavailabilitiesv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getpatientbookingavailabilitiesbypatientbookingavailabilityidv1.md): Returns the patient booking availability V1 identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putpatientbookingavailabilitiesbypatientbookingavailabilityidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deletepatientbookingavailabilitiesbypatientbookingavailabilityidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
 - [GET /v1/scheduletemplates](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplatesv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [POST /v1/scheduletemplates](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postscheduletemplatesv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplatesbyscheduletemplateidv1.md): Returns the schedule template (V1) identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putscheduletemplatesbyscheduletemplateidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deletescheduletemplatesbyscheduletemplateidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
 - [GET /v1/scheduleopenings](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduleopeningsv1.md): Returns available openings for a location and date range (provider hours, schedule items, templates). **Required in `filter`:** `location.id`, `startDate`, `endDate` (`YYYY-MM-DD`), span ≤ **14** days
 - [GET /v1/scheduletemplateappointmentreasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplateappointmentreasonsv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [POST /v1/scheduletemplateappointmentreasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postscheduletemplateappointmentreasonsv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplateappointmentreasonsbyscheduletemplateappointmentreasonidv1.md): Returns the schedule template appointment reason V1 identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putscheduletemplateappointmentreasonsbyscheduletemplateappointmentreasonidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deletescheduletemplateappointmentreasonsbyscheduletemplateappointmentreasonidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
 - [GET /v1/scheduletemplatereasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplatereasonsv1.md): **Query shape:** Prefer a **narrow** filter—combine scoping filters with `lastModified` or date bounds where supported. A very wide date range with no other scoping can **408** (timeout) on large tena
 - [POST /v1/scheduletemplatereasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/postscheduletemplatereasonsv1.md): Creates a resource from the request body. Validation errors return **400**; a successful create returns **201** with the created resource in `data`.
 - [GET /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/getscheduletemplatereasonsbyscheduletemplatereasonidv1.md): Returns the schedule template reason (V1) identified by the path parameter. **404** when the resource is missing or not accessible in the organization context.
 - [PUT /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/putscheduletemplatereasonsbyscheduletemplatereasonidv1.md): Updates the resource identified by the path parameter. Validation errors return **400**; **404** when the resource is missing.
 - [DELETE /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/other/deletescheduletemplatereasonsbyscheduletemplatereasonidv1.md): Deletes the resource identified by the path parameter. **404** when the resource is missing or already deleted.
