# Public API – Appointment Management Operations related to patients, appointments, providers and so on. Version: 185.0.9 ## 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 ## Download OpenAPI description [Public API – Appointment Management](https://papidocs.hs1api.com/_bundle/PublicAPI/api-appointment-management.yaml) ## Appointments (V1) Appointments endpoints ### Returns a list of Appointments (V1) based on filter criteria - [GET /v1/appointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/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 408 (timeout) on large tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no appointments matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated; lastModified / lastId style pagination is preferred. ### Returns AppointmentV1 which has been created - [POST /v1/appointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/postappointmentsv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns a list of Appointments (V1) asynchronously based on filter criteria - [GET /v1/appointments/async](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no Appointments matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns an AppointmentV1 by ID. - [GET /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/getappointmentsbyappointmentidv1.md): Returns the appointment identified by the path parameter. 404 when the appointment is missing or not accessible in the organization context. ### Returns the updated AppointmentV1. - [PUT /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/putappointmentsbyappointmentidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific AppointmentV1 by ID - [DELETE /v1/appointments/{appointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointments-(v1)/deleteappointmentsbyappointmentidv1.md): Permanently deletes the appointment and cascades related tasks, history, and recare links. 404 when the resource is missing or already deleted. ## AppointmentColor (V1) AppointmentColor endpoints ### Returns a list of AppointmentColors (V1) - [GET /v1/appointmentcolors](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmentcolor-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no AppointmentColors matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns an AppointmentColor (V1) by ID. - [GET /v1/appointmentcolors/{appointmentColorId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmentcolor-(v1)/getappointmentcolorsbyappointmentcoloridv1.md): Returns the AppointmentColor (V1) identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ### Returns the updated AppointmentColor (V1). - [PUT /v1/appointmentcolors/{appointmentColorId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmentcolor-(v1)/putappointmentcolorsbyappointmentcoloridv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ## AppointmentHistory (V1) AppointmentHistory endpoints ### Returns a list of AppointmentHistory (V1) based on filter criteria - [GET /v1/appointmenthistories](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenthistory-(v1)/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 with a smaller window. Empty results: 200 with data: [] means no AppointmentHistory matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. ### Returns an AppointmentHistoryV1 by ID. - [GET /v1/appointmenthistories/{appointmentHistoryId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenthistory-(v1)/getappointmenthistoriesbyappointmenthistoryidv1.md): Returns the AppointmentHistoryV1 identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## AppointmentStatusHistory (V1) AppointmentStatusHistory endpoints ### Returns a list of AppointmentStatusHistory (V1) based on filter criteria - [GET /v1/appointmentstatushistories](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmentstatushistory-(v1)/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 with a smaller window. Empty results: 200 with data: [] means no AppointmentStatusHistory matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. ### Returns an AppointmentStatusHistoryV1 by ID. - [GET /v1/appointmentstatushistories/{appointmentStatusHistoryId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmentstatushistory-(v1)/getappointmentstatushistoriesbyappointmentstatushistoryidv1.md): Returns the AppointmentStatusHistoryV1 identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ## AppointmentTasks (V1) AppointmentTasks endpoints ### Returns a list of AppointmentTasks (V1) based on filter criteria - [GET /v1/appointmenttasks](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenttasks-(v1)/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 with a smaller window or use cursor pagination (lastId—see parameter descriptions). Empty results: 200 with data: [] means no appointment tasks matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated; lastId style pagination is preferred. See the Public API pagination documentation. ### Returns AppointmentTaskV1 which has been created - [POST /v1/appointmenttasks](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenttasks-(v1)/postappointmenttasksv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns an AppointmentTaskV1 by appointment task ID. - [GET /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenttasks-(v1)/getappointmenttasksbyappointmenttaskidv1.md): Returns the AppointmentTaskV1 identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ### Returns the updated AppointmentTaskV1. - [PUT /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenttasks-(v1)/putappointmenttasksbyappointmenttaskidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific AppointmentTaskV1 by ID - [DELETE /v1/appointmenttasks/{appointmentTaskId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/appointmenttasks-(v1)/deleteappointmenttasksbyappointmenttaskidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## Events (V1) Events endpoints ### Returns the created EventV1 - [POST /v1/events](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/createevent.md): Creates a new event. Supports recurring events with weekly or monthly patterns. ### Returns a list of Events (V1) based on filter criteria - [GET /v1/events](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/getallevents.md): Retrieves events based on filter criteria. Supports pagination and various filtering options. ### Returns a list of Events (V1) asynchronously based on filter criteria - [GET /v1/events/async](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/getalleventsasync.md): Retrieves events asynchronously. Returns the first 10 results immediately and streams all matching records to the Streaming API. ### Returns an Event (V1) by ID - [GET /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/geteventbyid.md): Retrieves a specific event by its ID. Returns detailed event information including location, operatory, and recurrence settings if applicable. ### Updates an Event (V1) by ID - [PUT /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/updateevent.md): Updates an existing event. Supports updating single occurrences or entire recurring series based on the recurrenceTarget parameter. ### Deletes an Event (V1) by ID - [DELETE /v1/events/{eventId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/events-(v1)/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. ## Missed Appointments (V1) Missed Appointments endpoints ### Returns a list of missed appointments based on filter criteria - [GET /v1/missedappointments](https://papidocs.hs1api.com/publicapi/api-appointment-management/missed-appointments-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no missed appointments matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns a missed appointment by missed appointment ID. - [GET /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/missed-appointments-(v1)/getmissedappointmentsbymissedappointmentidv1.md): Returns the missed appointment identified by the path parameter. 404 when the resource is missing or not accessible in the organization context. ### Returns the updated missed appointment. - [PUT /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/missed-appointments-(v1)/putmissedappointmentsbymissedappointmentidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific missed appointment by ID - [DELETE /v1/missedappointments/{missedAppointmentId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/missed-appointments-(v1)/deletemissedappointmentsbymissedappointmentidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## ScheduleOpenings (V1) ScheduleOpenings endpoints ### Returns a list of schedule openings based on filter criteria. But Provider Hours MUST be specified before calling this API. - [GET /v1/scheduleopenings](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduleopenings-(v1)/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. Do not combine scheduleTemplate.id with booking.type or reason.id. Invalid mixes or missing keys return 400. MCP agents: If you need a location id, call get_locations and choose from data (id, name). The response data array is one row per provider + operatory + day, each with slots (start / end in the location time zone; optional template metadata may appear). Omitting provider / operatory filters can return many rows—narrow with provider.id / operatory.id in filter, or pass responseFields to return fewer fields per row. Use ignoreProviderHours when you want location hours for every selected provider instead of provider-hour records (see that parameter). ## ScheduleTemplates (V1) ScheduleTemplates endpoints ### Returns a list of schedule templates (V1) based on filter criteria - [GET /v1/scheduletemplates](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplates-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no schedule templates matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns schedule template (V1) which has been created - [POST /v1/scheduletemplates](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplates-(v1)/postscheduletemplatesv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns a schedule template (V1) by schedule template ID. - [GET /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplates-(v1)/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. ### Returns the updated schedule template. - [PUT /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplates-(v1)/putscheduletemplatesbyscheduletemplateidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific schedule template (V1) by ID - [DELETE /v1/scheduletemplates/{scheduleTemplateId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplates-(v1)/deletescheduletemplatesbyscheduletemplateidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## ScheduleTemplateReasons (V1) ScheduleTemplateReasons endpoints ### Returns a list of schedule template reasons (V1) based on filter criteria - [GET /v1/scheduletemplatereasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplatereasons-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no schedule template reasons matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns schedule template reason (V1) which has been created - [POST /v1/scheduletemplatereasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplatereasons-(v1)/postscheduletemplatereasonsv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns a schedule template reason (V1) by schedule template reason ID. - [GET /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplatereasons-(v1)/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. ### Returns the updated schedule template reason (V1). - [PUT /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplatereasons-(v1)/putscheduletemplatereasonsbyscheduletemplatereasonidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific schedule template reason (V1) by ID - [DELETE /v1/scheduletemplatereasons/{scheduleTemplateReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplatereasons-(v1)/deletescheduletemplatereasonsbyscheduletemplatereasonidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## ScheduleTemplateAppointmentReasons (V1) ScheduleTemplateAppointmentReasons endpoints ### Returns a list of schedule template appointment reasons (V1) based on filter criteria - [GET /v1/scheduletemplateappointmentreasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplateappointmentreasons-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no schedule template appointment reasons matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns schedule template appointment reason V1 which has been created - [POST /v1/scheduletemplateappointmentreasons](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplateappointmentreasons-(v1)/postscheduletemplateappointmentreasonsv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns a schedule template appointment reason V1 by schedule template appointment reason ID. - [GET /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplateappointmentreasons-(v1)/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. ### Returns the updated schedule template appointment reason V1. - [PUT /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplateappointmentreasons-(v1)/putscheduletemplateappointmentreasonsbyscheduletemplateappointmentreasonidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific schedule template appointment reason V1 by ID - [DELETE /v1/scheduletemplateappointmentreasons/{scheduleTemplateAppointmentReasonId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/scheduletemplateappointmentreasons-(v1)/deletescheduletemplateappointmentreasonsbyscheduletemplateappointmentreasonidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted. ## PatientBookingAvailabilities (V1) PatientBookingAvailabilities endpoints ### Returns a list of patient booking availabilities V1 based on filter criteria - [GET /v1/patientbookingavailabilities](https://papidocs.hs1api.com/publicapi/api-appointment-management/patientbookingavailabilities-(v1)/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 tenants; retry with a smaller window or use cursor pagination (lastId with lastModified—see parameter descriptions). Empty results: 200 with data: [] means no patient booking availabilities V1 matched; it does not indicate invalid filter values. responseFields: Use only names allowed on this operation (see the responseFields parameter). Use ALL or the documented flat field list. Pagination: The page query parameter is deprecated where lastId is supported; lastModified / lastId style pagination is preferred. ### Returns patient booking availability V1 which has been created - [POST /v1/patientbookingavailabilities](https://papidocs.hs1api.com/publicapi/api-appointment-management/patientbookingavailabilities-(v1)/postpatientbookingavailabilitiesv1.md): Creates a resource from the request body. Validation errors return 400; a successful create returns 201 with the created resource in data. ### Returns a patient booking availability V1 by patient booking availability ID. - [GET /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/patientbookingavailabilities-(v1)/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. ### Returns the updated patient booking availability V1. - [PUT /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/patientbookingavailabilities-(v1)/putpatientbookingavailabilitiesbypatientbookingavailabilityidv1.md): Updates the resource identified by the path parameter. Validation errors return 400; 404 when the resource is missing. ### Delete specific patient booking availability V1 by ID - [DELETE /v1/patientbookingavailabilities/{patientBookingAvailabilityId}](https://papidocs.hs1api.com/publicapi/api-appointment-management/patientbookingavailabilities-(v1)/deletepatientbookingavailabilitiesbypatientbookingavailabilityidv1.md): Deletes the resource identified by the path parameter. 404 when the resource is missing or already deleted.