Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Calendar

Manage appointments, calendar events, working hours, and schedule availability.

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 Working Hours

Working hours define the availability windows for care team users, or availability for encounters.

POST Create Work Hours

POST /{tenantName}/{instanceName}/calendar/work-hours

Creates working hours or availability.

Required fields:

  • psmId — ID of the user whose working hours (or, for an availability, the encounter host) are being set

  • type — WORKING_HOURS if creating working hours for a user, or AVAILABILITY if creating availability for an encounter

  • ruleType — DEFAULT for regular hours or OVERRIDE for exceptions in the schedule

  • startDateTime

  • daysInfo (day, startTime, endTime)

Optional fields:

  • endDateTime

About endDateTime:

The endDateTime parameter helps distinguish current hours from historical ones:

  • endDateTime = null — no end date; this is the current active schedule (open-ended, "from today onward").

  • endDateTime = a past date — archived record, active during the period between startDateTime and endDateTime.

How to interpret the combinations:

type = WORKING_HOURS / AVAILABILITY + ruleType = DEFAULT:

  • endDateTime = past date → archived working hours, active during that period

  • endDateTime = null → current working hours, in use right now

type = WORKING_HOURS / AVAILABILITY + ruleType = OVERRIDE:

  • endDateTime = past date → an exception that has already expired

  • endDateTime = future date → an active exception, not yet expired (bounded window, so endDateTime is required)

If an availability is created, include an encounters block in the body listing all encounters that will have this availability, e.g. "encounters": ["etmp-a1"].

Example Request

GET Read Work Hours

GET /{tenantName}/{instanceName}/calendar/work-hours

Retrieves working hours or availability for the specified users and date range.

About endDateTime:

The endDateTime field on each returned record helps distinguish current hours from historical ones:

  • endDateTime = null — no end date; this is the current active schedule (open-ended, "from today onward").

  • endDateTime = a past date — archived record, active during the period between startDateTime and endDateTime.

How to interpret the combinations:

type = WORKING_HOURS / AVAILABILITY + ruleType = DEFAULT:

  • endDateTime = past date → archived working hours, active during that period

  • endDateTime = null → current working hours, in use right now

type = WORKING_HOURS / AVAILABILITY + ruleType = OVERRIDE:

  • endDateTime = past date → an exception that has already expired

  • endDateTime = future date → an active exception, not yet expired (bounded window, so endDateTime is required)

Query Parameters

Parameter
Type
Required
Description

psmIds

string

No

Comma-separated list of user IDs

from

string

Yes

Date-time in ISO-8601 format

to

string

Yes

Date-time in ISO-8601 format

Example Request

PUT Update Work Hours

PUT /{tenantName}/{instanceName}/calendar/work-hours/{workHoursId}

Updates working hours or availability by ID.

  • type — WORKING_HOURS if updating working hours, or AVAILABILITY if updating availability for an encounter

  • ruleType — DEFAULT for regular hours or OVERRIDE for exceptions in the schedule

  • endDateTime — helps distinguish current hours from historical ones:

    • endDateTime = null — no end date; this is the current active schedule (open-ended, "from today onward").

    • endDateTime = a past date — archived record, active during the period between startDateTime and endDateTime.

How to interpret the combinations:

type = WORKING_HOURS / AVAILABILITY + ruleType = DEFAULT:

  • endDateTime = past date → archived working hours, active during that period

  • endDateTime = null → current working hours, in use right now

type = WORKING_HOURS / AVAILABILITY + ruleType = OVERRIDE:

  • endDateTime = past date → an exception that has already expired

  • endDateTime = future date → an active exception, not yet expired (bounded window, so endDateTime is required)

If updating an availability, include the encounters block in the body (same format as Create).

Example Request

Calendar Events

A typical calendar API to create and manage events. The participants field must contain a participant with id equal to the hostId.

URL structure: /{tenantName}/{instanceName}/calendar/events

Field values:

Field
Supported values

eventType

APPOINTMENT, LEAVE, ENCOUNTER

eventStatus

SCHEDULED, CANCELLED, COMPLETED, MISSED

eventMode

IN-PERSON, CALL, VIDEO

participantRole

patient, psm

POST Create Event

POST /{tenantName}/{instanceName}/calendar/events

Creates a calendar event.

Required fields:

  • startDateTime

  • endDateTime

  • hostId

  • participants (participantId, participantRole)

Note: eventColor is required — otherwise the event will be white and not visible in the Welkin UI. For appointments use "eventColor": "green"; for leave events use "eventColor": "grey".

Example Request

GET Get Event by ID

GET /{tenantName}/{instanceName}/calendar/events/{eventId}

Returns a specific calendar event by its ID.

Example Request

GET Get Event by External ID

GET /{tenantName}/{instanceName}/calendar/events/{externalId}?type=EXTERNAL_ID

Same as "Get Event by ID", but looks up the event by its externalId instead of the internal id.

Query Parameters

Parameter
Type
Required
Description

type

string

Yes

Must be EXTERNAL_ID to look up by external ID

viewerTimezone

string

No

Timezone (IANA format). If provided, returns local-time fields; otherwise uses the timezone of the psmId user

Example Request

GET Find Events

GET /{tenantName}/{instanceName}/calendar/events

Search for calendar events matching the given filters.

Query Parameters

Parameter
Type
Required
Description

from

string

Yes

Date-time in ISO-8601 format

to

string

Yes

Date-time in ISO-8601 format

participantIds

string

No

List of user or patient IDs

eventType

string

No

One of APPOINTMENT, LEAVE, ENCOUNTER

includeCancelled

boolean

No

Whether to return cancelled events; default false

includeEncounterInfo

boolean

No

Whether to include the encounterInfo field (present for ENCOUNTER events); default false

excludeAssignedToEncounterEvents

boolean

No

If true, only returns events not assigned to an encounter; default false

sort

string

No

Sort order of the returned collection, e.g. createdAt,asc

viewerTimezone

string

No

Timezone (IANA format) for local-time fields

Example Request

PUT Update Calendar Event by ID

PUT /{tenantName}/{instanceName}/calendar/events/{eventId}

Full replace of the event.

Required fields:

  • startDateTime

  • endDateTime

  • hostId

  • participants (participantId, participantRole)

Example Request

PATCH Patch Update Event by ID

PATCH /{tenantName}/{instanceName}/calendar/events/{eventId}

Partial update — send only the fields you want to change.

Example Request

GET Get Summary for the User

GET /{tenantName}/{instanceName}/calendar/psm-event-summary

Returns an event summary for the specified users and date range.

Query Parameters

Parameter
Type
Required
Description

psmIds

string

Yes

Comma-separated list of user IDs

from

string

Yes

Date-time in ISO-8601 format

to

string

Yes

Date-time in ISO-8601 format

Example Request

DELETE Delete Calendar Event by ID

DELETE /{tenantName}/{instanceName}/calendar/events/{eventId}

Deletes a calendar event by its ID.

Note: only future events can be deleted.

Example Request

PUT Update Event Invitation Response by ID

PUT /{tenantName}/{instanceName}/calendar/events/{eventId}/invitation-response

Updates a participant's response to an event invitation.

Note: all fields are required.

Example Request

Schedule

Two APIs are available for retrieving user schedules: Get Schedules and Get Available Schedules.

GET Get Schedules

GET /{tenantName}/{instanceName}/calendar/psm-schedules

Returns schedule information for the specified users over the given period: working hours, availability for encounters, and all events in the calendar.

Query Parameters

Parameter
Type
Required
Description

psmIds

string

Yes

Comma-separated list of user IDs

from

string

Yes

Date-time in ISO-8601 format

to

string

Yes

Date-time in ISO-8601 format

workHoursType

string

No

Filter by working hours type. Accepts WORKING_HOURS or AVAILABILITY.

Example Request

GET Get Available Schedules

GET /{tenantName}/{instanceName}/calendar/available-psm-schedules

Checks availability of users for the specified period and returns working hours, availabilities for encounters, and all events in the calendar. If a user has no working hours set for the period, they are considered unavailable and no information is returned for them.

Query Parameters

Parameter
Type
Required
Description

psmIds

string

Yes

Comma-separated list of user IDs

from

string

Yes

Date-time in ISO-8601 format

to

string

Yes

Date-time in ISO-8601 format

workHoursType

string

No

Filter by working hours type. Accepts WORKING_HOURS or AVAILABILITY.

Example Request

Last updated

Was this helpful?