> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/calendar-api.md). # Calendar API **Note:** 1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format. If API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied. For UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`) ## Read Work Hours > 1\. HTTP Method: GET\ > 2\. HTTP URL: \` > \ > \ > URL examples:\ > \ > 1\. \` ?psm-ids=301b2895-cbf0-4cac-b4cf-1d082faee95c \&from=2020-01-01T00:00:00.000Z \&to=2020-01-31T23:59:59.000Z\`\ > 2\. \` ?psm-ids=301b2895-cbf0-4cac-b4cf-1d082faee95c,18f393a8-62b3-4b4b-aa42-da769ce4489a \&from=2020-01-01T00:00:00.000Z \&to=2020-01-31T23:59:59.000Z\` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarWorkHours":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"details":{"type":"array","items":{"$ref":"#/components/schemas/WorkHoursDetails"}}}},"WorkHoursDetails":{"type":"object","properties":{"workHoursId":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Only present when type is AVAILABILITY."}}},"CalendarWorkHoursType":{"type":"string","enum":["WORKING_HOURS","AVAILABILITY"]},"CalendarWorkHoursRuleType":{"type":"string","enum":["DEFAULT","OVERRIDE"]},"CalendarDaysInfo":{"type":"object","properties":{"daysInfoId":{"type":"string","format":"uuid","readOnly":true},"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO day of week (1=Monday .. 7=Sunday)"},"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/work-hours":{"get":{"summary":"Read Work Hours","tags":["Calendar API"],"operationId":"Read_Work_Hours","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"psmIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"List of id and values"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"viewerTimezone","in":"query","required":false,"schema":{"type":"string"},"description":"If provided, return localtime fields (localStartDateTime, localEndDateTime) with provided timezone, otherwise use timezone for psmId user. String timezone (IANA format)."}],"responses":{"200":{"description":"List of work hours (requires psmIds and a from/to date range)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CalendarWorkHours"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: GET\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/work-hours`\n \n\nURL examples:\n\n1. `https://api.live.welkincloud.io/gh/sb-demo/calendar/work-hours ?psm-ids=301b2895-cbf0-4cac-b4cf-1d082faee95c &from=2020-01-01T00:00:00.000Z &to=2020-01-31T23:59:59.000Z`\n2. `https://api.live.welkincloud.io/gh/sb-demo/calendar/work-hours ?psm-ids=301b2895-cbf0-4cac-b4cf-1d082faee95c,18f393a8-62b3-4b4b-aa42-da769ce4489a &from=2020-01-01T00:00:00.000Z &to=2020-01-31T23:59:59.000Z`"}}}} ``` ## Create Work Hours > 1\. HTTP Method: POST\ > \ > 2\. HTTP URL: \` > \ > \ > \### Work Hours required fields\ > \ > \- psmId\ > \ > \- type - WORKING\_HOURS, if creating working hours for a user or AVAILABILITY, if creating availability for an encounter\ > \ > \- startDateTime\ > \ > \- endDateTime\ > \ > \- daysInfo\ > \ > \- daysInfo.startTime\ > \ > \- daysInfo.endTime\ > \ > \- daysInfo.day\ > \ > \ > If an availability is created, it is necessary to specify an encounters block in the body, inside of which you should list all encounters that will have this availability. Example:\ > \ > \`"encounters": \[\`\ > \ > \`"etmp-a1"\`\ > \ > \`]\` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarWorkHours":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"details":{"type":"array","items":{"$ref":"#/components/schemas/WorkHoursDetails"}}}},"WorkHoursDetails":{"type":"object","properties":{"workHoursId":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Only present when type is AVAILABILITY."}}},"CalendarWorkHoursType":{"type":"string","enum":["WORKING_HOURS","AVAILABILITY"]},"CalendarWorkHoursRuleType":{"type":"string","enum":["DEFAULT","OVERRIDE"]},"CalendarDaysInfo":{"type":"object","properties":{"daysInfoId":{"type":"string","format":"uuid","readOnly":true},"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO day of week (1=Monday .. 7=Sunday)"},"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"}}},"CalendarWorkHoursRequest":{"type":"object","required":["psmId","startDateTime","ruleType","daysInfo"],"properties":{"psmId":{"type":"string","format":"uuid"},"workHoursId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType","default":"WORKING_HOURS"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"description":"Required when type is AVAILABILITY."}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/work-hours":{"post":{"summary":"Create Work Hours","tags":["Calendar API"],"operationId":"Create_Work_Hours","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"responses":{"201":{"description":"Work hours created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarWorkHours"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: POST\n \n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/work-hours`\n \n\n### Work Hours required fields\n\n- psmId\n \n- type - WORKING_HOURS, if creating working hours for a user or AVAILABILITY, if creating availability for an encounter\n \n- startDateTime\n \n- endDateTime\n \n- daysInfo\n \n- daysInfo.startTime\n \n- daysInfo.endTime\n \n- daysInfo.day\n \n\nIf an availability is created, it is necessary to specify an encounters block in the body, inside of which you should list all encounters that will have this availability. Example:\n\n`\"encounters\": [`\n\n`\"etmp-a1\"`\n\n`]`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarWorkHoursRequest"}}}}}}}} ``` ## Update Work Hours > Updating work hours or avability by ID.\ > \ > type - WORKING\_HOURS, if updating working hours or AVAILABILITY, if updating availability for an encounter\ > \ > If an availability is updating, it is necessary to specify an encounters block in the body, inside of which you should list all encounters that will have this availability. Example:\ > \ > \`"encounters": \[\`\ > \ > \`"etmp-a1"\`\ > \ > \`]\`\ > \ > 1\. HTTP Method: PUT\ > \ > 2\. HTTP URL: \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"WorkHoursId":{"name":"workHoursId","in":"path","required":true,"description":"UUID of the work hours record","schema":{"type":"string","format":"uuid"}}},"schemas":{"CalendarWorkHours":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"details":{"type":"array","items":{"$ref":"#/components/schemas/WorkHoursDetails"}}}},"WorkHoursDetails":{"type":"object","properties":{"workHoursId":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Only present when type is AVAILABILITY."}}},"CalendarWorkHoursType":{"type":"string","enum":["WORKING_HOURS","AVAILABILITY"]},"CalendarWorkHoursRuleType":{"type":"string","enum":["DEFAULT","OVERRIDE"]},"CalendarDaysInfo":{"type":"object","properties":{"daysInfoId":{"type":"string","format":"uuid","readOnly":true},"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO day of week (1=Monday .. 7=Sunday)"},"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"}}},"CalendarWorkHoursRequest":{"type":"object","required":["psmId","startDateTime","ruleType","daysInfo"],"properties":{"psmId":{"type":"string","format":"uuid"},"workHoursId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType","default":"WORKING_HOURS"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"description":"Required when type is AVAILABILITY."}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/work-hours/{workHoursId}":{"put":{"summary":"Update Work Hours","tags":["Calendar API"],"operationId":"Update_Work_Hours","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/WorkHoursId"}],"responses":{"200":{"description":"Updated work hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarWorkHours"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Updating work hours or avability by ID.\n\ntype - WORKING_HOURS, if updating working hours or AVAILABILITY, if updating availability for an encounter\n\nIf an availability is updating, it is necessary to specify an encounters block in the body, inside of which you should list all encounters that will have this availability. Example:\n\n`\"encounters\": [`\n\n`\"etmp-a1\"`\n\n`]`\n\n1. HTTP Method: PUT\n \n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/work-hours/c7a4251f-d70e-4ccb-8c96-1038c76fd737`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarWorkHoursRequest"}}}}}}}} ``` ## Find Events > 1\. HTTP Method: GET\ > 2\. HTTP URL: \` > \ > \ > Example URLs:\ > \ > 1\. \` > 2\. \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarEventPage":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/CalendarEvent"}}}}]},"PaginatedResponse":{"type":"object","description":"Standard paginated response wrapper.","properties":{"content":{"type":"array","items":{"type":"object"}},"pageable":{"$ref":"#/components/schemas/PageableInfo"},"totalElements":{"type":"integer","description":"Total number of matching records"},"totalPages":{"type":"integer","description":"Total number of pages"},"last":{"type":"boolean"},"first":{"type":"boolean"},"number":{"type":"integer","description":"Current page number (zero-based)"},"size":{"type":"integer","description":"Page size"},"numberOfElements":{"type":"integer","description":"Number of elements on the current page"},"empty":{"type":"boolean"},"sort":{"$ref":"#/components/schemas/SortInfo"}}},"PageableInfo":{"type":"object","properties":{"sort":{"$ref":"#/components/schemas/SortInfo"},"pageSize":{"type":"integer"},"pageNumber":{"type":"integer"},"offset":{"type":"integer"},"unpaged":{"type":"boolean"},"paged":{"type":"boolean"}}},"SortInfo":{"type":"object","properties":{"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"CalendarEvent":{"type":"object","required":["startDateTime","endDateTime","hostId","participants"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"externalId":{"type":"string","nullable":true},"externalIdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"eventTitle":{"type":"string","nullable":true},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"allDayEvent":{"type":"boolean"},"duration":{"type":"integer","readOnly":true,"nullable":true},"eventType":{"type":"string","description":"Free text — commonly one of CalendarEventType's values."},"eventStatus":{"type":"string","description":"Free text — commonly one of CalendarEventStatus's values."},"eventMode":{"type":"string","description":"Free text — commonly one of DeliveryMethod's values."},"eventColor":{"type":"string","nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"acuityAppointmentId":{"type":"integer","nullable":true},"externalCalendarEventId":{"type":"string","nullable":true},"encounterInfo":{"$ref":"#/components/schemas/CalendarEventEncounterInfo","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata","nullable":true}}},"CalendarEventEncounterInfo":{"type":"object","required":["encounterId"],"properties":{"encounterId":{"type":"string","format":"uuid"},"dispositionId":{"type":"string","format":"uuid","nullable":true},"templateName":{"type":"string","nullable":true},"templateTitle":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/EncounterStatus"},"serviceCost":{"type":"integer","nullable":true},"preVisitCost":{"type":"integer","nullable":true},"responsibleParty":{"$ref":"#/components/schemas/ResponsibleParty"},"visitServices":{"type":"array","items":{"$ref":"#/components/schemas/EncounterVisitService"}},"location":{"type":"string","nullable":true}}},"EncounterStatus":{"type":"string","enum":["DRAFT","OPEN","CANCELED","CANCELLED","FINALIZED"]},"ResponsibleParty":{"type":"string","enum":["SELF_PAY","INSURANCE","UNKNOWN"],"deprecated":true},"EncounterVisitService":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number","default":1},"serviceCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"cancellationFee":{"type":"integer","nullable":true,"description":"Cost in cents"},"preVisitCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"modifiers":{"type":"array","items":{"type":"string"}}}},"CalendarParticipant":{"type":"object","required":["participantId","participantRole"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"participantId":{"type":"string","format":"uuid"},"participantRole":{"$ref":"#/components/schemas/CalendarParticipantRole"},"participationStatus":{"$ref":"#/components/schemas/ParticipationStatus"},"attended":{"type":"boolean"},"timezone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"deleted":{"type":"boolean","nullable":true},"hasAccess":{"type":"boolean","nullable":true},"hiddenPhi":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"birthDate":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","nullable":true}}},"CalendarParticipantRole":{"type":"string","enum":["patient","psm"]},"ParticipationStatus":{"type":"string","enum":["UNKNOWN","DECLINED","TENTATIVE","ACCEPTED"]},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"ExternalEventMetadata":{"type":"object","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEventParticipant"}},"calendarProvider":{"$ref":"#/components/schemas/CalendarProvider"}}},"ExternalEventParticipant":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/ParticipationStatus"},"owner":{"type":"boolean"}}},"CalendarProvider":{"type":"string","enum":["GOOGLE","MICROSOFT"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events":{"get":{"summary":"Find Events","tags":["Calendar API"],"operationId":"Find_Events","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format , required"},{"name":"participantIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"List of id and values, either users or"},{"name":"eventType","in":"query","required":false,"schema":{"type":"string"},"description":"Enum of allowed values (\"APPOINTMENT\", \"LEAVE\", \"ENCOUNTER\")"},{"name":"includeCancelled","in":"query","required":false,"schema":{"type":"boolean"},"description":"Should or not API return cancelled events (default: false)"},{"name":"includeEncounterInfo","in":"query","required":false,"schema":{"type":"boolean"},"description":"Should or not API include encounterInfo field into dto (the field is exists for events with ENCOUNTER event type) (default: false)"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format, required"},{"name":"excludeAssignedToEncounterEvents","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, only events that are not assigned to encounter will returns (default: false)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Allows one to specify the sort order of the returned patients collection"},{"name":"viewerTimezone","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of calendar events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEventPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: GET\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/`\n \n\nExample URLs:\n\n1. `https://api.live.welkincloud.io/gh/sb-demo/calendar/events?from=2020-01-15T14:00:00.000Z&participantIds=301b2895-cbf0-4cac-b4cf-1d082faee95c&sort=createdAt,asc&to=2020-02-11T00:00:00.000Z&eventType=APPOINTMENT`\n2. `https://api.live.welkincloud.io/gh/sb-demo/calendar/events?from=2020-01-15T14:00:00.000Z&to=2020-02-11T00:00:00.000Z&eventType=ENCOUNTER&includeEncounterInfo=true`"}}}} ``` ## Create Event > Request to create an event in Calendar.\ > \ > \*\*NOTE:\*\* It's required to fill "eventColor", otherwise it will be white and not visible on Welkin UI.\ > \ > For Appointments it should be "eventColor": "green" and for Leave event "eventColor": "grey".\ > \ > \### Event required fields\ > \ > \- startDateTime\ > \- endDateTime\ > \- hostId\ > \- participants\ > \- participants.participantId\ > \- participants.participantRole\ > \ > \ > 1\. HTTP Method: POST\ > 2\. HTTP URL: \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarEvent":{"type":"object","required":["startDateTime","endDateTime","hostId","participants"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"externalId":{"type":"string","nullable":true},"externalIdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"eventTitle":{"type":"string","nullable":true},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"allDayEvent":{"type":"boolean"},"duration":{"type":"integer","readOnly":true,"nullable":true},"eventType":{"type":"string","description":"Free text — commonly one of CalendarEventType's values."},"eventStatus":{"type":"string","description":"Free text — commonly one of CalendarEventStatus's values."},"eventMode":{"type":"string","description":"Free text — commonly one of DeliveryMethod's values."},"eventColor":{"type":"string","nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"acuityAppointmentId":{"type":"integer","nullable":true},"externalCalendarEventId":{"type":"string","nullable":true},"encounterInfo":{"$ref":"#/components/schemas/CalendarEventEncounterInfo","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata","nullable":true}}},"CalendarEventEncounterInfo":{"type":"object","required":["encounterId"],"properties":{"encounterId":{"type":"string","format":"uuid"},"dispositionId":{"type":"string","format":"uuid","nullable":true},"templateName":{"type":"string","nullable":true},"templateTitle":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/EncounterStatus"},"serviceCost":{"type":"integer","nullable":true},"preVisitCost":{"type":"integer","nullable":true},"responsibleParty":{"$ref":"#/components/schemas/ResponsibleParty"},"visitServices":{"type":"array","items":{"$ref":"#/components/schemas/EncounterVisitService"}},"location":{"type":"string","nullable":true}}},"EncounterStatus":{"type":"string","enum":["DRAFT","OPEN","CANCELED","CANCELLED","FINALIZED"]},"ResponsibleParty":{"type":"string","enum":["SELF_PAY","INSURANCE","UNKNOWN"],"deprecated":true},"EncounterVisitService":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number","default":1},"serviceCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"cancellationFee":{"type":"integer","nullable":true,"description":"Cost in cents"},"preVisitCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"modifiers":{"type":"array","items":{"type":"string"}}}},"CalendarParticipant":{"type":"object","required":["participantId","participantRole"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"participantId":{"type":"string","format":"uuid"},"participantRole":{"$ref":"#/components/schemas/CalendarParticipantRole"},"participationStatus":{"$ref":"#/components/schemas/ParticipationStatus"},"attended":{"type":"boolean"},"timezone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"deleted":{"type":"boolean","nullable":true},"hasAccess":{"type":"boolean","nullable":true},"hiddenPhi":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"birthDate":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","nullable":true}}},"CalendarParticipantRole":{"type":"string","enum":["patient","psm"]},"ParticipationStatus":{"type":"string","enum":["UNKNOWN","DECLINED","TENTATIVE","ACCEPTED"]},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"ExternalEventMetadata":{"type":"object","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEventParticipant"}},"calendarProvider":{"$ref":"#/components/schemas/CalendarProvider"}}},"ExternalEventParticipant":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/ParticipationStatus"},"owner":{"type":"boolean"}}},"CalendarProvider":{"type":"string","enum":["GOOGLE","MICROSOFT"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events":{"post":{"summary":"Create Event","tags":["Calendar API"],"operationId":"Create_Event","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"viewerTimezone","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"201":{"description":"Created calendar event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to create an event in Calendar.\n\n**NOTE:** It's required to fill \"eventColor\", otherwise it will be white and not visible on Welkin UI.\n\nFor Appointments it should be \"eventColor\": \"green\" and for Leave event \"eventColor\": \"grey\".\n\n### Event required fields\n\n- startDateTime\n- endDateTime\n- hostId\n- participants\n- participants.participantId\n- participants.participantRole\n \n\n1. HTTP Method: POST\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}}}}}} ``` ## Get Event By External ID > 1\. HTTP Method: GET\ > 2\. HTTP URL: \` > \ > \ > \| Parameters | Format | Description |\ > \| --- | --- | --- |\ > \| viewerTimezone | String timezone (IANA format) | If provided, return localtime fields (localStartDateTime, localEndDateTime) with provided timezone, otherwise use timezone for psmId user | ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"EventId":{"name":"eventId","in":"path","required":true,"description":"UUID of the calendar event","schema":{"type":"string","format":"uuid"}}},"schemas":{"CalendarEvent":{"type":"object","required":["startDateTime","endDateTime","hostId","participants"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"externalId":{"type":"string","nullable":true},"externalIdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"eventTitle":{"type":"string","nullable":true},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"allDayEvent":{"type":"boolean"},"duration":{"type":"integer","readOnly":true,"nullable":true},"eventType":{"type":"string","description":"Free text — commonly one of CalendarEventType's values."},"eventStatus":{"type":"string","description":"Free text — commonly one of CalendarEventStatus's values."},"eventMode":{"type":"string","description":"Free text — commonly one of DeliveryMethod's values."},"eventColor":{"type":"string","nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"acuityAppointmentId":{"type":"integer","nullable":true},"externalCalendarEventId":{"type":"string","nullable":true},"encounterInfo":{"$ref":"#/components/schemas/CalendarEventEncounterInfo","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata","nullable":true}}},"CalendarEventEncounterInfo":{"type":"object","required":["encounterId"],"properties":{"encounterId":{"type":"string","format":"uuid"},"dispositionId":{"type":"string","format":"uuid","nullable":true},"templateName":{"type":"string","nullable":true},"templateTitle":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/EncounterStatus"},"serviceCost":{"type":"integer","nullable":true},"preVisitCost":{"type":"integer","nullable":true},"responsibleParty":{"$ref":"#/components/schemas/ResponsibleParty"},"visitServices":{"type":"array","items":{"$ref":"#/components/schemas/EncounterVisitService"}},"location":{"type":"string","nullable":true}}},"EncounterStatus":{"type":"string","enum":["DRAFT","OPEN","CANCELED","CANCELLED","FINALIZED"]},"ResponsibleParty":{"type":"string","enum":["SELF_PAY","INSURANCE","UNKNOWN"],"deprecated":true},"EncounterVisitService":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number","default":1},"serviceCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"cancellationFee":{"type":"integer","nullable":true,"description":"Cost in cents"},"preVisitCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"modifiers":{"type":"array","items":{"type":"string"}}}},"CalendarParticipant":{"type":"object","required":["participantId","participantRole"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"participantId":{"type":"string","format":"uuid"},"participantRole":{"$ref":"#/components/schemas/CalendarParticipantRole"},"participationStatus":{"$ref":"#/components/schemas/ParticipationStatus"},"attended":{"type":"boolean"},"timezone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"deleted":{"type":"boolean","nullable":true},"hasAccess":{"type":"boolean","nullable":true},"hiddenPhi":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"birthDate":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","nullable":true}}},"CalendarParticipantRole":{"type":"string","enum":["patient","psm"]},"ParticipationStatus":{"type":"string","enum":["UNKNOWN","DECLINED","TENTATIVE","ACCEPTED"]},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"ExternalEventMetadata":{"type":"object","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEventParticipant"}},"calendarProvider":{"$ref":"#/components/schemas/CalendarProvider"}}},"ExternalEventParticipant":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/ParticipationStatus"},"owner":{"type":"boolean"}}},"CalendarProvider":{"type":"string","enum":["GOOGLE","MICROSOFT"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events/{eventId}":{"get":{"summary":"Get Event By External ID","tags":["Calendar API"],"operationId":"Get_Event_By_External_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/EventId"},{"name":"type","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeEncounterInfo","in":"query","required":false,"description":"If true, include encounter details when the event is linked to an encounter.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Calendar event (disambiguate by the `type` query param: ID, EXTERNAL_ID, EXTERNAL_CALENDAR_EVENT_ID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: GET\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/externalId?type=EXTERNAL_ID`\n \n\n| Parameters | Format | Description |\n| --- | --- | --- |\n| viewerTimezone | String timezone (IANA format) | If provided, return localtime fields (localStartDateTime, localEndDateTime) with provided timezone, otherwise use timezone for psmId user |"}}}} ``` ## Update Calendar Event by ID > 1\. HTTP Method: PUT\ > 2\. HTTP URL: \` > \ > \ > \### Event required fields:\ > \ > \* startDateTime\ > \* endDateTime\ > \* hostId\ > \* participants\ > \* participants.participantId\ > \* participants.participantRole ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"EventId":{"name":"eventId","in":"path","required":true,"description":"UUID of the calendar event","schema":{"type":"string","format":"uuid"}}},"schemas":{"CalendarEvent":{"type":"object","required":["startDateTime","endDateTime","hostId","participants"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"externalId":{"type":"string","nullable":true},"externalIdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"eventTitle":{"type":"string","nullable":true},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"allDayEvent":{"type":"boolean"},"duration":{"type":"integer","readOnly":true,"nullable":true},"eventType":{"type":"string","description":"Free text — commonly one of CalendarEventType's values."},"eventStatus":{"type":"string","description":"Free text — commonly one of CalendarEventStatus's values."},"eventMode":{"type":"string","description":"Free text — commonly one of DeliveryMethod's values."},"eventColor":{"type":"string","nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"acuityAppointmentId":{"type":"integer","nullable":true},"externalCalendarEventId":{"type":"string","nullable":true},"encounterInfo":{"$ref":"#/components/schemas/CalendarEventEncounterInfo","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata","nullable":true}}},"CalendarEventEncounterInfo":{"type":"object","required":["encounterId"],"properties":{"encounterId":{"type":"string","format":"uuid"},"dispositionId":{"type":"string","format":"uuid","nullable":true},"templateName":{"type":"string","nullable":true},"templateTitle":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/EncounterStatus"},"serviceCost":{"type":"integer","nullable":true},"preVisitCost":{"type":"integer","nullable":true},"responsibleParty":{"$ref":"#/components/schemas/ResponsibleParty"},"visitServices":{"type":"array","items":{"$ref":"#/components/schemas/EncounterVisitService"}},"location":{"type":"string","nullable":true}}},"EncounterStatus":{"type":"string","enum":["DRAFT","OPEN","CANCELED","CANCELLED","FINALIZED"]},"ResponsibleParty":{"type":"string","enum":["SELF_PAY","INSURANCE","UNKNOWN"],"deprecated":true},"EncounterVisitService":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number","default":1},"serviceCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"cancellationFee":{"type":"integer","nullable":true,"description":"Cost in cents"},"preVisitCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"modifiers":{"type":"array","items":{"type":"string"}}}},"CalendarParticipant":{"type":"object","required":["participantId","participantRole"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"participantId":{"type":"string","format":"uuid"},"participantRole":{"$ref":"#/components/schemas/CalendarParticipantRole"},"participationStatus":{"$ref":"#/components/schemas/ParticipationStatus"},"attended":{"type":"boolean"},"timezone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"deleted":{"type":"boolean","nullable":true},"hasAccess":{"type":"boolean","nullable":true},"hiddenPhi":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"birthDate":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","nullable":true}}},"CalendarParticipantRole":{"type":"string","enum":["patient","psm"]},"ParticipationStatus":{"type":"string","enum":["UNKNOWN","DECLINED","TENTATIVE","ACCEPTED"]},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"ExternalEventMetadata":{"type":"object","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEventParticipant"}},"calendarProvider":{"$ref":"#/components/schemas/CalendarProvider"}}},"ExternalEventParticipant":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/ParticipationStatus"},"owner":{"type":"boolean"}}},"CalendarProvider":{"type":"string","enum":["GOOGLE","MICROSOFT"]}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events/{eventId}":{"put":{"summary":"Update Calendar Event by ID","tags":["Calendar API"],"operationId":"Update_Calendar_Event_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Updated calendar event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: PUT\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/2dfbd113-5282-4f70-b456-d8cf7ecb5573`\n \n\n### Event required fields:\n\n* startDateTime\n* endDateTime\n* hostId\n* participants\n* participants.participantId\n* participants.participantRole","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}}}}}} ``` ## Delete Calendar Event by ID > Note: Only future events can be deleted\ > \ > EndFragmentStartFragment\ > \ > 1\. HTTP Method: DELETE\ > 2\. HTTP URL: \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events/{eventId}":{"delete":{"summary":"Delete Calendar Event by ID","tags":["Calendar API"],"operationId":"Delete_Calendar_Event_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"eventId","in":"path","required":true,"description":"UUID of the calendar event","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Calendar event cancelled"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Note: Only future events can be deleted\n\nEndFragmentStartFragment\n\n1. HTTP Method: DELETE\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/2dfbd113-5282-4f70-b456-d8cf7ecb5573`"}}}} ``` ## Patch update Event by ID > 1\. HTTP Method: PATCH\ > 2\. HTTP URL: \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"EventId":{"name":"eventId","in":"path","required":true,"description":"UUID of the calendar event","schema":{"type":"string","format":"uuid"}}},"schemas":{"CalendarEvent":{"type":"object","required":["startDateTime","endDateTime","hostId","participants"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"externalId":{"type":"string","nullable":true},"externalIdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"eventTitle":{"type":"string","nullable":true},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"allDayEvent":{"type":"boolean"},"duration":{"type":"integer","readOnly":true,"nullable":true},"eventType":{"type":"string","description":"Free text — commonly one of CalendarEventType's values."},"eventStatus":{"type":"string","description":"Free text — commonly one of CalendarEventStatus's values."},"eventMode":{"type":"string","description":"Free text — commonly one of DeliveryMethod's values."},"eventColor":{"type":"string","nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"acuityAppointmentId":{"type":"integer","nullable":true},"externalCalendarEventId":{"type":"string","nullable":true},"encounterInfo":{"$ref":"#/components/schemas/CalendarEventEncounterInfo","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata","nullable":true}}},"CalendarEventEncounterInfo":{"type":"object","required":["encounterId"],"properties":{"encounterId":{"type":"string","format":"uuid"},"dispositionId":{"type":"string","format":"uuid","nullable":true},"templateName":{"type":"string","nullable":true},"templateTitle":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/EncounterStatus"},"serviceCost":{"type":"integer","nullable":true},"preVisitCost":{"type":"integer","nullable":true},"responsibleParty":{"$ref":"#/components/schemas/ResponsibleParty"},"visitServices":{"type":"array","items":{"$ref":"#/components/schemas/EncounterVisitService"}},"location":{"type":"string","nullable":true}}},"EncounterStatus":{"type":"string","enum":["DRAFT","OPEN","CANCELED","CANCELLED","FINALIZED"]},"ResponsibleParty":{"type":"string","enum":["SELF_PAY","INSURANCE","UNKNOWN"],"deprecated":true},"EncounterVisitService":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"quantity":{"type":"number","default":1},"serviceCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"cancellationFee":{"type":"integer","nullable":true,"description":"Cost in cents"},"preVisitCost":{"type":"integer","nullable":true,"description":"Cost in cents"},"modifiers":{"type":"array","items":{"type":"string"}}}},"CalendarParticipant":{"type":"object","required":["participantId","participantRole"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"participantId":{"type":"string","format":"uuid"},"participantRole":{"$ref":"#/components/schemas/CalendarParticipantRole"},"participationStatus":{"$ref":"#/components/schemas/ParticipationStatus"},"attended":{"type":"boolean"},"timezone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"deleted":{"type":"boolean","nullable":true},"hasAccess":{"type":"boolean","nullable":true},"hiddenPhi":{"type":"boolean"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"gender":{"$ref":"#/components/schemas/PatientGender"},"birthDate":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","nullable":true}}},"CalendarParticipantRole":{"type":"string","enum":["patient","psm"]},"ParticipationStatus":{"type":"string","enum":["UNKNOWN","DECLINED","TENTATIVE","ACCEPTED"]},"PatientGender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]},"ExternalEventMetadata":{"type":"object","properties":{"participants":{"type":"array","items":{"$ref":"#/components/schemas/ExternalEventParticipant"}},"calendarProvider":{"$ref":"#/components/schemas/CalendarProvider"}}},"ExternalEventParticipant":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"$ref":"#/components/schemas/ParticipationStatus"},"owner":{"type":"boolean"}}},"CalendarProvider":{"type":"string","enum":["GOOGLE","MICROSOFT"]},"CalendarEventUpdateRequest":{"type":"object","description":"Partial update — all fields optional.","properties":{"externalId":{"type":"string","nullable":true},"eventTitle":{"type":"string"},"eventDescription":{"type":"string","nullable":true},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"allDayEvent":{"type":"boolean"},"eventType":{"type":"string"},"eventStatus":{"type":"string"},"eventMode":{"type":"string"},"eventColor":{"type":"string","nullable":true},"additionalInfo":{"type":"object","additionalProperties":true,"nullable":true},"hostId":{"type":"string","format":"uuid"},"timezone":{"type":"string"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/CalendarParticipant"}},"externalCalendarEventId":{"type":"string","nullable":true},"externalEventMetadata":{"$ref":"#/components/schemas/ExternalEventMetadata"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/events/{eventId}":{"patch":{"summary":"Patch update Event by ID","tags":["Calendar API"],"operationId":"Patch_update_Event_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Updated calendar event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEvent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: PATCH\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/2dfbd113-5282-4f70-b456-d8cf7ecb5573`","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarEventUpdateRequest"}}}}}}}} ``` ## Get Summary for the User > 1\. HTTP Method: GET\ > 2\. HTTP URL: \` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarPSMEventSummary":{"type":"object","properties":{"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"summary":{"type":"array","items":{"$ref":"#/components/schemas/CalendarSummaryItem"}}}},"CalendarSummaryItem":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"totalCreatedEvents":{"type":"integer"},"totalOccurredEvents":{"type":"integer"},"totalFutureEvents":{"type":"integer"},"eventStatusCount":{"type":"object","additionalProperties":{"type":"integer"}},"totalWorkingHours":{"type":"string"},"totalEventHours":{"type":"string"},"occupancy":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/psm-event-summary":{"get":{"summary":"Get Summary for the User","tags":["Calendar API"],"operationId":"Get_Summary_for_the_User","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"psmIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"User id"}],"responses":{"200":{"description":"Event/working-hours summary per PSM","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarPSMEventSummary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: GET\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/psm-event-summary?from=2020-01-15T14:00:00.000Z&to=2020-02-11T00:00:00.000Z&psmIds=301b2895-cbf0-4cac-b4cf-1d082faee95c`"}}}} ``` ## Get Schedules > The request returns information about the schedule of users for the specified period: working hours, availability for encounters, all events in the calendar\ > \ > Example:\ > \ > \` ?psmIds=28f393a8-62b3-4b4b-aa42-da769ce4489a,18f393a8-62b3-4b4b-aa42-da769ce4489a \&from=2020-01-01T00:00:00.000Z \&to=2020-01-31T23:59:59.000Z\` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarPSMSchedule":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"workHours":{"type":"array","items":{"$ref":"#/components/schemas/WorkHoursDetails"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleEvent"}}}},"WorkHoursDetails":{"type":"object","properties":{"workHoursId":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Only present when type is AVAILABILITY."}}},"CalendarWorkHoursType":{"type":"string","enum":["WORKING_HOURS","AVAILABILITY"]},"CalendarWorkHoursRuleType":{"type":"string","enum":["DEFAULT","OVERRIDE"]},"CalendarDaysInfo":{"type":"object","properties":{"daysInfoId":{"type":"string","format":"uuid","readOnly":true},"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO day of week (1=Monday .. 7=Sunday)"},"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"}}},"CalendarScheduleEvent":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid","description":"Duplicate of eventId."},"eventTitle":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true},"eventColor":{"type":"string","nullable":true},"allDayEvent":{"type":"boolean"},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/psm-schedules":{"get":{"summary":"Get Schedules","tags":["Calendar API"],"operationId":"Get_Schedules","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"psmIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"List of id and values"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"workHoursType","in":"query","required":false,"schema":{"type":"string"},"description":"WORKING_HOURS or AVAILABILITY"}],"responses":{"200":{"description":"List of PSM schedules (work hours + events)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CalendarPSMSchedule"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"The request returns information about the schedule of users for the specified period: working hours, availability for encounters, all events in the calendar\n\nExample:\n\n`https://api.live.welkincloud.io/gh/sb-demo/calendar/psm-schedules ?psmIds=28f393a8-62b3-4b4b-aa42-da769ce4489a,18f393a8-62b3-4b4b-aa42-da769ce4489a &from=2020-01-01T00:00:00.000Z &to=2020-01-31T23:59:59.000Z`"}}}} ``` ## Get Available Schedules > The request checks the availability of users for the specified period and returns information about working hours, availabilities for encounters and all events in the calendar. In order for the information to be displayed for a user, the user must have working hours set for the specified period. If the user does not have working hours in the specified period, he is considered unavailable and the information will not be displayed for him\ > \ > Example:\ > \ > \` ?psmIds=28f393a8-62b3-4b4b-aa42-da769ce4489a,18f393a8-62b3-4b4b-aa42-da769ce4489a \&from=2020-01-01T00:00:00.000Z \&to=2020-01-31T23:59:59.000Z\` ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"CalendarPSMSchedule":{"type":"object","properties":{"psmId":{"type":"string","format":"uuid"},"workHours":{"type":"array","items":{"$ref":"#/components/schemas/WorkHoursDetails"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleEvent"}}}},"WorkHoursDetails":{"type":"object","properties":{"workHoursId":{"type":"string","format":"uuid","readOnly":true},"createdBy":{"type":"string","format":"uuid","readOnly":true},"updatedBy":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","nullable":true},"type":{"$ref":"#/components/schemas/CalendarWorkHoursType"},"ruleType":{"$ref":"#/components/schemas/CalendarWorkHoursRuleType"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time","nullable":true},"localStartDateTime":{"type":"string","format":"date-time","readOnly":true},"localEndDateTime":{"type":"string","format":"date-time","readOnly":true},"daysInfo":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDaysInfo"}},"encounters":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Only present when type is AVAILABILITY."}}},"CalendarWorkHoursType":{"type":"string","enum":["WORKING_HOURS","AVAILABILITY"]},"CalendarWorkHoursRuleType":{"type":"string","enum":["DEFAULT","OVERRIDE"]},"CalendarDaysInfo":{"type":"object","properties":{"daysInfoId":{"type":"string","format":"uuid","readOnly":true},"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO day of week (1=Monday .. 7=Sunday)"},"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"}}},"CalendarScheduleEvent":{"type":"object","properties":{"eventId":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid","description":"Duplicate of eventId."},"eventTitle":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true},"eventColor":{"type":"string","nullable":true},"allDayEvent":{"type":"boolean"},"startDateTime":{"type":"string","format":"date-time"},"localStartDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"localEndDateTime":{"type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/calendar/available-psm-schedules":{"get":{"summary":"Get Available Schedules","tags":["Calendar API"],"operationId":"Get_Available_Schedules","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"psmIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"List of id and values"},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Date_time in ISO-8601 format"},{"name":"workHoursType","in":"query","required":false,"schema":{"type":"string"},"description":"WORKING_HOURS or AVAILABILITY"}],"responses":{"200":{"description":"List of available PSM schedules","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CalendarPSMSchedule"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"The request checks the availability of users for the specified period and returns information about working hours, availabilities for encounters and all events in the calendar. In order for the information to be displayed for a user, the user must have working hours set for the specified period. If the user does not have working hours in the specified period, he is considered unavailable and the information will not be displayed for him\n\nExample:\n\n`https://api.live.welkincloud.io/gh/sb-demo/calendar/psm-schedules ?psmIds=28f393a8-62b3-4b4b-aa42-da769ce4489a,18f393a8-62b3-4b4b-aa42-da769ce4489a &from=2020-01-01T00:00:00.000Z &to=2020-01-31T23:59:59.000Z`"}}}} ``` ## Update Event invitation response by ID > 1\. HTTP Method: PUT\ > 2\. HTTP URL: \` > \ > \ > Note: all fields are required ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Calendar API","description":"**Note:**\n\n1. Calendar API includes read only date fields (such as `localStartDateTime` or `localEndDateTime`) with the timezone applied. Such fields use [ISO-8601](https://www.w3.org/TR/NOTE-datetime) datetime format.\n \n\nIf API caller is a user (not API CLIENT), that user timezone will be applied. If caller is an API CLIENT, that timezone of event user host id will be applied.\n\nFor UTC time you should use field without `local` prefix (such as `startDateTime` and `endDateTime`)"}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}},"schemas":{"CalendarInvitationResponseRequest":{"type":"object","required":["participantId","participationStatus"],"properties":{"participantId":{"type":"string","format":"uuid"},"participationStatus":{"type":"string","description":"e.g. Yes, No, Maybe"}}}}},"paths":{"/{tenantName}/{instanceName}/calendar/events/{eventId}/invitation-response":{"put":{"summary":"Update Event invitation response by ID","tags":["Calendar API"],"operationId":"Update_Event_invitation_response_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"eventId","in":"path","required":true,"description":"UUID of the calendar event","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invitation response recorded"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"1. HTTP Method: PUT\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/calendar/events/2dfbd113-5282-4f70-b456-d8cf7ecb5573/invitation-response`\n \n\nNote: all fields are required","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarInvitationResponseRequest"}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.welkinhealth.com/api-reference/calendar-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.