Calendars API
List calendars
List all calendars for an account:
GET /calendars
Response
Status: 200 OK
[
{
"name": "24x5 (Monday through Friday)",
"created_at": "2016-03-14T03:09:47-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:09:47-06:00",
"id": 32,
"calendar_hours": [
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "mon"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "tue"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "wed"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "thu"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "fri"
}
],
"source": null,
"disabled": true
},
{
"name": "24x6 (Monday through Saturday)",
"created_at": "2016-03-14T03:09:47-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:09:47-06:00",
"id": 33,
"calendar_hours": [
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "mon"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "tue"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "wed"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "thu"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "fri"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "sat"
}
],
"source": null
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of calendars.
Predefined Filters
The following predefined filters are available:
/calendars/disabled
: List all disabled calendars/calendars/enabled
: List all enabled calendars
Collection Fields
By default the following fields will appear in collections of calendars:
id
source
sourceID
name
calendar_hours
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
sourceID
name
disabled
created_at
updated_at
The filters on sourceID
and name
are not case sensitive.
Sorting
By default a collection of calendars is sorted ascending by name
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
name
created_at
updated_at
Get a single calendar
GET /calendars/:id
Response
Status: 200 OK
{
"name": "24x5 (Monday through Friday)",
"created_at": "2016-03-14T03:09:47-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:09:47-06:00",
"disabled": false,
"id": 32,
"calendar_hours": [
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "mon"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "tue"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "wed"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "thu"
},
{
"time_until": "00:00",
"time_from": "00:00",
"weekday": "fri"
}
],
"source": null
}
The response contains these fields.
Get a duration
Calculate the duration between a start and end time for a specific calendar:
GET /calendars/:id/duration/?start=:time&end=:time&time_zone=:timezone"
The API returns the number of minutes between the start and end, including only the time during which the calendar is active and excluding any holidays that are linked to the calendar.
The time zone that is to be applied to the calendar is optional. If a time zone is not specified, the default UTC time zone is applied.
Examples
The total number of calendar minutes for the month of January 2020:
$ curl -u "api-token:x" -X GET -H "X-4me-Account: wdc" https://api.r-service.tech/v1/calendars/42/duration?start=2020-01-01T00:00:00Z&end=2020-02-01T00:00:00Z
The number of calendar minutes between 9am and 5pm Eastern Time (which is GMT-05:00) on January 20, 2020 where the time zone for the calendar is Central Time (which is GMT-06:00):
$ curl -u "api-token:x" -X GET -H "X-4me-Account: wdc" -d '{"start":"2020-01-20T09:00:00-05:00", "end":"2020-01-20T17:00:00-05:00", "time_zone":"Central Time (US & Canada)"}' "https://api.r-service.tech/v1/calendars/42/duration"
Create a calendar
POST /calendars
When creating a new calendar these fields are available.
Response
Status: 201 Created
{
"calendar_hours": "...",
"...": "..."
}
The response contains all fields of the created calendar and is similar to the response in Get a single calendar
Update a calendar
PATCH /calendars/:id
When updating a calendar these fields are available.
Response
Status: 200 OK
{
"calendar_hours": "...",
"...": "..."
}
The response contains all fields of the updated calendar and is similar to the response in Get a single calendar
Fields
- calendar_hours
- Readonly aggregated calendar hours
- created_at
- Readonly datetime — The date and time at which the calendar was created.
- disabled
- Optional boolean, default:
false
— The Disabled box is checked when the calendar may no longer be related to other records. - id
- Readonly integer — The unique ID of the calendar.
- name
- Required string (max 80) — The Name field is used to enter the name of the calendar.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- updated_at
- Readonly datetime — The date and time of the last update of the calendar. If the calendar has no updates it contains the
created_at
value.