API docs by Redocly

Calendar Opening Hours API (v5.0)

Search all calendars

Get all calendars that match the given query

query Parameters
id
Array of strings <uuid>

The list of calendar IDs to retrieve, sent as separate parameters (?id=aaaa&id=bbbb...). If this list is passed, calendars must have an ID in this list in addition to any additional criteria.

servicePointId
Array of strings <uuid>

Filter for calendars that are assigned to a certain service point. If this parameter is excluded, all service points will be considered/included in the response. Multiple service points may be specified with form-style query expansions; in this case, calendars that are assigned to any of the provided service points will be returned.

startDate
string <date>

The first date (YYYY-MM-DD) to consider, inclusively

endDate
string <date>

The last date (YYYY-MM-DD) to consider, inclusively

offset
integer >= 0
Default: 0

Skip a certain number of the first values; used for pagination

limit
integer >= 0
Default: 10

The maximum number of elements returned in the response, used for pagination. A limit of zero will not include any results (however, totalRecords will still be included) -- to include all results, use a large number such as 2147483647.

Responses

Response samples

Content type
application/json
{
  • "calendars": [
    ],
  • "totalRecords": 1
}

Create a new calendar

Create a new calendar from a provided body. If an ID is provided for the calendar, it will be ignored (and a new one generated).

Request Body schema: application/json
id
string <uuid>

A unique UUID identifying this calendar

name
required
string

A user-provided name used to label this calendar

startDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this calendar

endDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this calendar

assignments
required
Array of strings <uuid> (servicePointId)

A list of all service points that this calendar is assigned to

required
Array of objects (normalHours)

A list of objects describing when the calendar is normally open

Array
calendarId
string <uuid>

The UUID of the calendar which these hours are for

startDay
required
string <Weekday> (weekday)

A day of the week. Either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY

startTime
required
string <time>

The time when this opening starts, inclusive

endDay
required
string <Weekday> (weekday)

A day of the week. Either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY

endTime
required
string <time>

The last minute of this opening, inclusive (11:59 if it should be open at 11:59 and closed at 12:00)

required
Array of objects (exceptionRange)

A list of objects describing exceptions to the normal hours

Array
calendarId
string <uuid>

The UUID of the calendar which this exception is for

name
required
string

A user-provided label for this exception

startDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this exception range

endDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this exception range

required
Array of objects (exceptionalOpening)

The openings during this exception

object (metadata)

Metadata associated with the calendar. This is provided by the server on a best-effort basis; no fields are guaranteed to be present. Metadata is provided from Okapi; any metadata sent directly from the client will be ignored.

createdDate
string <date-time>
createdByUserId
string <uuid>
updatedDate
string <date-time>
updatedByUserId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Spring Calendar",
  • "startDate": "2022-01-08",
  • "endDate": "2022-05-09",
  • "assignments": [
    ],
  • "normalHours": [
    ],
  • "exceptions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "Sample Spring Calendar",
  • "startDate": "2022-01-08",
  • "endDate": "2022-05-09",
  • "assignments": [
    ],
  • "normalHours": [
    ],
  • "exceptions": [
    ]
}

Delete multiple calendars

Delete a calendar by its ID.

query Parameters
id
required
Array of strings <uuid> non-empty

A list of calendars to delete, sent as separate parameters (?id=aaaa&id=bbbb...). If any calendars are missing, a 404 will be returned and nothing modified.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "summary": "The request could not be parsed/understood."
}

Get a calendar

Get a calendar's information by its ID.

path Parameters
calendarId
required
string <uuid>

The calendar ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "name": "Sample Spring Calendar",
  • "startDate": "2022-01-08",
  • "endDate": "2022-05-09",
  • "assignments": [
    ],
  • "normalHours": [
    ],
  • "exceptions": [
    ]
}

Update an existing calendar

Overwrite an existing calendar with the provided payload. The provided calendar must already exist (attempting to overwrite a calendar that does not yet exist will result in a 404). If the payload includes any IDs, they will be ignored, and the existing calendar ID reused.

path Parameters
calendarId
required
string <uuid>

The calendar ID to replace

Request Body schema: application/json
id
string <uuid>

A unique UUID identifying this calendar

name
required
string

A user-provided name used to label this calendar

startDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this calendar

endDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this calendar

assignments
required
Array of strings <uuid> (servicePointId)

A list of all service points that this calendar is assigned to

required
Array of objects (normalHours)

A list of objects describing when the calendar is normally open

Array
calendarId
string <uuid>

The UUID of the calendar which these hours are for

startDay
required
string <Weekday> (weekday)

A day of the week. Either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY

startTime
required
string <time>

The time when this opening starts, inclusive

endDay
required
string <Weekday> (weekday)

A day of the week. Either SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY

endTime
required
string <time>

The last minute of this opening, inclusive (11:59 if it should be open at 11:59 and closed at 12:00)

required
Array of objects (exceptionRange)

A list of objects describing exceptions to the normal hours

Array
calendarId
string <uuid>

The UUID of the calendar which this exception is for

name
required
string

A user-provided label for this exception

startDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this exception range

endDate
required
string <date>

The first effective date (inclusive, YYYY-MM-DD) of this exception range

required
Array of objects (exceptionalOpening)

The openings during this exception

object (metadata)

Metadata associated with the calendar. This is provided by the server on a best-effort basis; no fields are guaranteed to be present. Metadata is provided from Okapi; any metadata sent directly from the client will be ignored.

createdDate
string <date-time>
createdByUserId
string <uuid>
updatedDate
string <date-time>
updatedByUserId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Spring Calendar",
  • "startDate": "2022-01-08",
  • "endDate": "2022-05-09",
  • "assignments": [
    ],
  • "normalHours": [
    ],
  • "exceptions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "Sample Spring Calendar",
  • "startDate": "2022-01-08",
  • "endDate": "2022-05-09",
  • "assignments": [
    ],
  • "normalHours": [
    ],
  • "exceptions": [
    ]
}

Delete a calendar

Delete a calendar by its ID.

path Parameters
calendarId
required
string <uuid>

The calendar ID to operate on.

Responses

Response samples

Content type
application/json
{
  • "value": {
    },
  • "summary": "The request could not be parsed/understood."
}

Surrounding openings

Calculate openings nearest to a given date for a specified service point

path Parameters
servicePointId
required
string <uuid>

The service point to calculate openings on

query Parameters
date
required
string <date>

The date (YYYY-MM-DD) to calculate openings around

Responses

Response samples

Content type
application/json
{
  • "openings": [
    ]
}

Daily opening information

Calculate the opening information for each date within a range

path Parameters
servicePointId
required
string <uuid>

The service point to calculate openings on

query Parameters
startDate
required
string <date>

The first date (YYYY-MM-DD) to include, inclusive

endDate
required
string <date>

The last date (YYYY-MM-DD) to include, inclusive

includeClosed
required
boolean

Whether or not the results should include days where the service point is closed. Exceptional closures will always be returned

offset
integer >= 0
Default: 0

Skip a certain number of the first values; used for pagination

limit
integer >= 0
Default: 10

The maximum number of elements returned in the response, used for pagination. A limit of zero will not include any results (however, totalRecords will still be included) -- to include all results, use a large number such as 2147483647.

Responses

Response samples

Content type
application/json
{
  • "dates": [
    ],
  • "totalRecords": 3
}