Calendar REST API

The calendar REST API enables developers to interact with your website via third-party applications or external data sources.

Learn more about REST APIs.

The following actions can be done with the calendar REST API.

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'