Calendar REST API
The calendar REST API enables developers to interact with your website via third-party applications or external data sources.
The following actions can be done with the calendar REST API.
- Retrieve one or more events
- Retrieve a single event
- Add a new event
- Edit an event
- Partially edit an event
- Delete an event
- Upload a file or image
All requests are submitted to /api/v1/calendar/events and it's the type of request that determines the action that is performed. The exception is uploading a file. That is submitted to /api/vi/calendar/upload.
- GET - retrieve one or more events
- POST - add an event
- PUT - fully edit an event
- PATCH - partially edit an event
- DELETE - delete an event
Retrieve one or more events
Retrieve a list of events that supports paging and filtering using a GET request.
Request type
GET
Request URL
/api/v1/calendar/events
Full request
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events'
Response
Status: 200 OK
{
"data": [
{
"id": 23,
"title": "Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-01",
"endDate": "2017-04-01",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed",
"isAllDay": true,
"isStartEnd": true,
"isStartOnly": false,
"isTba": false,
"isNoTime": false
},
"isPastEvent": true,
"isToday": false,
"repeats": false,
"url": "/calendar/event/23",
"icalUrl": "/calendar/feed/event-ical/id/23",
"editUrl": "/calendar/event/edit/id/23"
},
{
...other events....
}
],
"pagination": {
"currentPage": 1,
"perPage": 20,
"count": 20,
"totalPages": 10,
"total": 200,
"links": {
"next": "?page=2&limit=20"
}
},
"totalItems": 200
}
Learn more about pagination within the REST API.
Parameters
Get more information about the common REST parameters.
| Parameter | Description |
|---|---|
| attributes | One or more attributes to filter the results by. Essentially this will search for items that have values that match the passed value for each attribute. Learn more |
| endDate | Optional date to get events before. Only events on or before the date will be retrieved. The date format follows the RFC3339 standard with the exception that the time does not need to be specified. YYYY-MM-DD Example 2017-04-01 |
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more |
| limit | The maximum number of items to retrieve. Learn more |
| page | The pagination page number to retrieve results for. Learn more |
| search | Search the events by the query value and only return matching events. Learn more |
| sort | Sets how to sort the results. Learn more |
| startDate | Optional date to get events after. Only events on or after the date will be retrieved. The date format follows the RFC3339 standard with the exception that the time does not need to be specified. YYYY-MM-DD Example 2017-04-01 |
Retrieve a specific event
Retrieve a single event identified by it's id using a GET request. In this example we're getting the event whose id is 13. The difference between this request and getting multiple events is that the id of the event is specified at the end of the URL.
Request type
GET
Request URL
/api/v1/calendar/events/13
Full request
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/13'
Response
{
"id": 13,
"title": "Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-01",
"endDate": "2017-04-01",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed",
"isAllDay": false,
"isStartEnd": true,
"isStartOnly": false,
"isTba": false,
"isNoTime": false
},
"isPastEvent": true,
"isToday": false,
"repeats": false,
"url": "/calendar/event/13",
"icalUrl": "/calendar/feed/event-ical/id/13",
"editUrl": "/calendar/event/edit/id/13"
}
Parameters
| Parameter | Description |
|---|---|
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more Example curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/13?instance=calendar-instance' |
Add a new event
Create a new event using a POST request. The data of the request should be a JSON object containing the attribute values for the event. Each key is the attribute layout key and the value is the attribute value to save with the event. Below is an example of the JSON data.
{
"title": "Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-01",
"endDate": "2017-04-01",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed"
},
"repeats": false
}
Minimum attributes that are required include:
- title
- date
- endDate
- time values
You can also include any custom attributes the same way as you would the default attributes.
Request type
POST
Request URL
/api/v1/calendar/events
Full request
curl -X POST -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "Event Title", "isFeatured": false, "description": "Event description", "date": "2017-04-01", "endDate": "2017-04-01", "isMultiDay": false, "spansMultipleDays": false, "showOnAllDates": true, "time": {"start": "09:30:00", "end": "13:30:00", "type": "timed"},"repeats": false}' 'http://www.mysite.com/api/v1/calendar/events'
Response
The response would be the full event information including it's id.
{
"id": 13,
"title": "Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-01",
"endDate": "2017-04-01",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed",
"isAllDay": false,
"isStartEnd": true,
"isStartOnly": false,
"isTba": false,
"isNoTime": false
},
"isPastEvent": true,
"isToday": false,
"repeats": false,
"url": "/calendar/event/13",
"icalUrl": "/calendar/feed/event-ical/id/13",
"editUrl": "/calendar/event/edit/id/13"
}
Parameters
| Parameter | Description |
|---|---|
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more Example curl -X POST -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "Event Title", "isFeatured": false, "description": "Event description", "date": "2017-04-01", "endDate": "2017-04-01", "isMultiDay": false, "spansMultipleDays": false, "showOnAllDates": true, "time": {"start": "09:30:00", "end": "13:30:00", "type": "timed"},"repeats": false}' 'http://www.mysite.com/api/v1/calendar/events?instance=calendar-instance' |
Edit an event
To fully edit an event you would submit a PUT request. The attributes values that you submit will be updated on the event. If any attributes are not submitted, then their values will be cleared out.
The request URL will include the id of the event to edit at the end of the URL.
In this example we're going to edit an event with an id of 27.
Request type
PUT
Request URL
/api/v1/calendar/events/27
Full request
curl -X PUT -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "Event Title", "isFeatured": false, "description": "Event description", "date": "2017-04-01", "endDate": "2017-04-01", "isMultiDay": false, "spansMultipleDays": false, "showOnAllDates": true, "time": {"start": "09:30:00", "end": "13:30:00", "type": "timed"},"repeats": false}' 'http://www.mysite.com/api/v1/calendar/events/27'
Response
The response would be the full event information including it's id.
{
"id": 27,
"title": "Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-01",
"endDate": "2017-04-01",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed",
"isAllDay": false,
"isStartEnd": true,
"isStartOnly": false,
"isTba": false,
"isNoTime": false
},
"isPastEvent": true,
"isToday": false,
"repeats": false,
"url": "/calendar/event/13",
"icalUrl": "/calendar/feed/event-ical/id/13",
"editUrl": "/calendar/event/edit/id/13"
}
Parameters
| Parameter | Description |
|---|---|
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more Example curl -X PUT -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "Event Title", "isFeatured": false, "description": "Event description", "date": "2017-04-01", "endDate": "2017-04-01", "isMultiDay": false, "spansMultipleDays": false, "showOnAllDates": true, "time": {"start": "09:30:00", "end": "13:30:00", "type": "timed"},"repeats": false}' 'http://www.mysite.com/api/v1/calendar/events/27?instance=calendar-instance' |
Partially edit an event
To partially edit an event you would submit a PATCH request. Only the attribute values that are submitted will be updated on the event. All other existing attribute values will be left unchanged.
In this example we're going to partially edit an event with an id of 27.
Request type
PATCH
Request URL
/api/v1/calendar/events/27
Full request
curl -X PATCH -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "New Event Title", "date": "2017-04-13", "endDate": "2017-04-13"}' 'http://www.mysite.com/api/v1/calendar/events/27'
Response
The response would be the full event information including it's id.
{
"id": 27,
"title": "New Event Title",
"isFeatured": false,
"description": "Event description",
"date": "2017-04-13",
"endDate": "2017-04-13",
"isMultiDay": false,
"spansMultipleDays": false,
"showOnAllDates": true,
"time": {
"start": "09:30:00",
"end": "13:30:00",
"type": "timed",
"isAllDay": false,
"isStartEnd": true,
"isStartOnly": false,
"isTba": false,
"isNoTime": false
},
"isPastEvent": true,
"isToday": false,
"repeats": false,
"url": "/calendar/event/27",
"icalUrl": "/calendar/feed/event-ical/id/27",
"editUrl": "/calendar/event/edit/id/27"
}
Parameters
| Parameter | Description |
|---|---|
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more Example curl -X PATCH -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"title": "New Event Title", "date": "2017-04-13", "endDate": "2017-04-13"}' 'http://www.mysite.com/api/v1/calendar/events/27?instance=calendar-instance' |
Delete an event
To delete an event you would submit a DELETE request. No response is returned if the deletion is successful. A HTTP status code of 204 is returned.
In this example we're going to delete an event with an id of 27.
Request type
DELETE
Request URL
/api/v1/calendar/events/27
Full request
curl -X DELETE -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/27'
Response
The response body will be empty. No JSON is returned. Rather, the response HTTP status code will be 204 if the deletion was successful.
Parameters
| Parameter | Description |
|---|---|
| instance | The instance key for the app. This is only needed if you have multiple instance of an app. Learn more Example curl -X DELETE -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/calendar/events/27?instance=calendar-instance' |
Uploading file or image
Uploading a file or image to an event is a two step process.
Step 1: Upload the file
Step 2: Edit the event and set the file path on the appropriate event attribute (or set the attribute value when adding an event).
When sending the upload request you must set the "Content-Type" header to "multipart/form-data".
Request type
POST
Request URL
/api/v1/calendar/upload
Full request
The attribute parameter is required. It's value is the layout key of the attribute that the file will be uploaded to. In our example we are uploading a PDF to an attribute whose layout key is 'brochure'. The attribute is configured to upload images to '/docs/event-brochure'.
curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -F 'upload=@local/path/to/file/myfile.pdf' 'http://devhosted.aptuitiv.com/api/v1/calendar/upload?attribute=brochure'
In the above example the "-F" curl parameter sets the appropriate Content-Type header for us. If you are not using curl then you will want to set the "Content-Type" header to "multipart/form-data".
Response
Below is an example response from successfully uploading a PDF.
{
"src": "/docs/event-brochure/myfile.pdf",
"fileName": "myfile.pdf",
"fileExtension": "pdf",
"type": "pdf",
"typeName": "PDF"
}
Below is an example response from successfully uploading an image.
{
"src": "/images/myimage.jpg",
"fileName": "myimage.jpg",
"fileExtension": "jpg",
"type": "image",
"typeName": "JPG Image",
"alt": "",
"height": "200",
"width": "300"
}
Step 2
Now that the file has been uploaded you can include it in an edit request or include it within an add event request. You would use the 'src' value.
For example, if you were editing an event you could do a partial edit after uploading the file.
curl -X PATCH -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"brochure": {"src": "/docs/event-brochure/myfile.pdf"}}' 'http://www.mysite.com/api/v1/calendar/events/27'