# Calendar

The Calendar API lets you manage appointments and calendar events for patients and care team members, configure working hours, and retrieve schedule availability.

**Base path:** `/{tenantName}/{instanceName}/`

***

## Calendar Events

### GET Get Calendar Events

**GET** `/{tenantName}/{instanceName}/calendar-events`

Returns calendar events across the instance, filterable by patient, user, or date range.

#### Query Parameters

| Parameter   | Type    | Description                    |
| ----------- | ------- | ------------------------------ |
| `patientId` | string  | Filter by patient UUID         |
| `userId`    | string  | Filter by care team user UUID  |
| `startDate` | string  | Start of date range (ISO 8601) |
| `endDate`   | string  | End of date range (ISO 8601)   |
| `page`      | integer | Page number                    |
| `size`      | integer | Results per page               |

#### Example Response `200 OK`

```json
{
  "data": [
    {
      "id": "event-uuid",
      "title": "Follow-up Appointment",
      "patientId": "a1b2c3d4",
      "userId": "user-uuid",
      "startTime": "2026-03-20T14:00:00Z",
      "endTime": "2026-03-20T14:30:00Z",
      "eventType": "APPOINTMENT",
      "status": "CONFIRMED"
    }
  ]
}
```

### POST Create Calendar Event

**POST** `/{tenantName}/{instanceName}/calendar-events`

### GET Get Calendar Event by ID

**GET** `/{tenantName}/{instanceName}/calendar-events/{eventId}`

### PATCH Update Calendar Event

**PATCH** `/{tenantName}/{instanceName}/calendar-events/{eventId}`

### DELETE Delete Calendar Event

**DELETE** `/{tenantName}/{instanceName}/calendar-events/{eventId}`

***

## Calendar Working Hours

Working hours define the availability windows for care team users.

### GET Get Working Hours

**GET** `/{tenantName}/{instanceName}/users/{userId}/working-hours`

### PUT Update Working Hours

**PUT** `/{tenantName}/{instanceName}/users/{userId}/working-hours`

***

## Schedule

### GET Get Schedule Availability

**GET** `/{tenantName}/{instanceName}/schedule/availability`

Returns open appointment slots based on working hours, existing bookings, and care team capacity.

#### Query Parameters

| Parameter   | Type    | Required | Description                             |
| ----------- | ------- | -------- | --------------------------------------- |
| `userId`    | string  | No       | Filter by specific user                 |
| `startDate` | string  | Yes      | Start of availability window (ISO 8601) |
| `endDate`   | string  | Yes      | End of availability window (ISO 8601)   |
| `duration`  | integer | No       | Desired appointment duration in minutes |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/api-reference/calendar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.