Calendar Events

Get Events

GET /calendarevents.json?startdate=YYYYMMDD&endDate=YYYYMMDD

This call will return all calendar events that the current user can see in the provided date range.

Optional parameters

  • showDeleted=true - Whether to include deleted events
  • updatedAfterDate=YYYYMMDDHHMMSS - Only return events updated after a certain datetime
  • eventTypeId - Only return events with a given eventTypeId (Numeric only - default 0)

Pagination:

By default we'll send back 250 records per page. Inspect the Response Headers for the following values:

  • X-Page (The current page being returned)
  • X-Pages (The total number of pages available)
  • X-Records (The total number of items available

You can request a specific page by calling the same API call and adding the parameter &page=n where n is the page you want. e.g: &page=2 for page 2, &page=5 for page 5.

Response

{
  "events": [
    {
      "where": "",
      "project-users-can-edit": false,
      "description": "Some sample Calendar Event",
      "attending-user-ids": "41858",
      "notify-user-names": "",
      "attending-user-names": "Michael H.",
      "status": "active",
      "owner": {
        "first-name": "Billy",
        "id": "29902",
        "last-name": "Mahony"
      },
      "reminders": [],
      "notify-user-ids": "",
      "start": "2014-05-27T00:00",
      "repeat": {},
      "all-day": true,
      "id": "195637",
      "end": "2014-06-10T23:59",
      "show-as-busy": false,
      "last-changed-on": "2014-04-30T11:06:18Z",
      "privacy": {
        "type": "company"
      },
      "attendees-can-edit": false,
      "type": {
        "name": "Holidays",
        "id": "100002",
        "color": "4E9075"
      },
      "title": "MJ Holidays"
    }
  ],
  "STATUS": "OK"
}


Get an Event

GET /calendarevents/{id}.json

Returns details about 1 specific event.

Request

GET /events/{id}.json

Response

{
  "event": {
    "where": "",
    "project-users-can-edit": false,
    "description": "",
    "attending-user-ids": "41858",
    "notify-user-names": "",
    "attending-user-names": "Michael H.",
    "owner": {
      "first-name": "Billy",
      "id": "29902",
      "last-name": "Mahony"
    },
    "reminders": [],
    "notify-user-ids": "",
    "start": "2014-05-27T00:00",
    "repeat": {},
    "all-day": true,
    "id": "195637",
    "end": "2014-06-10T23:59",
    "show-as-busy": false,
    "last-changed-on": "2014-04-30T11:06:18Z",
    "privacy": {
      "type": "company"
    },
    "attendees-can-edit": false,
    "type": {
      "name": "Holidays",
      "id": "100002",
      "color": "4E9075"
    },
    "title": "MJ Holidays"
  },
  "STATUS": "OK"
}


Create an event

POST/calendarevents.json

Create a calendar event.

Notes

  • "start" and "end" are in the format YYYY-MM-DDTHH:MM:SS (e.g: 2015-06-09T14:00:00 - always 24 hr)
  • "start" and "end" should be sent in the current users timezone 
  • "privacy" - default is "company"
    • "company"
    • "personal"
    • "project" - If passing "project" you need to send "project-id" along with "type"

Request

{
  "event" : {
    "start" : "YYYY-MM-DDThh:mm:ss",
    "end" : "YYYY-MM-DDThh:mm:ss",
    "all-day" : "true/false",
    "title" : "Some event title",
    "description" : "Some event description (optional)",
    "where" : "Some location (optional)",
    "privacy" : {
        "type" : "company",
        "project-id" : "0"
    },    
    "show-as-busy":"true/false",
    "type" : {
      "id" : "numeric calendarEventType id"
    },
    "attending-user-ids":"comma separated list of user id's",
    "notify-user-ids":"comma separated list of user id's",
    "notify":"true",
    "attendees-can-edit":"true/false",
    "project-users-can-edit":"true/false",
    "reminders" : [
      {
        "type":"string (one of the following sms,email,push)"
        "period":"string (one of the following minutes,hours,days,weeks)",
        "before":"numeric value (e.g: 15)"
      }  
    ]
  }
}

Response

  • Returns a HTTP status code of 201 for "Created" on success.
  • Returns the ID of the newly created event in the ID field

Create a recurring event

POST/calendarevents.json

Create a new recurring calendar event.

Notes

  • 'frequency' can be one of the following: weekly, weekdays, monthly, yearly, every2weeks, every3weeks, every4weeks, every2months, every3months, every4months, every6months

Request

{
   "event":{
      "start":"yyyy-mm-ddThh:mm",
      "end":"yyyy-mm-ddThh:mm",
      "all-day":false,
      "title":"My recurring event",
      "repeat":{
         "frequency":"monthly",
         "month-type":"monthday",
         "ends":true,
         "endDate":"yyyy-mm-dd"
      },
      "notify":true,
      "attendees-can-edit":false,
      "project-users-can-edit":false
   }
}

Response

  • Returns a HTTP status code of 201 for "Created" on success.
  • Returns the ID of the newly created event in the ID field

 


Edit an event

PUT /calendarevents/{id}.json

Edit a calendar event.

Notes

  • "start" and "end" are in the format YYYY-MM-DDTHH:MM:SS (e.g: 2015-06-09T14:00:00 - always 24 hr)
  • "start" and "end" should be sent in the current users timezone 
  • "privacy" - default is "company"
    • "company"
    • "personal"
    • "project" - If passing "project" you need to send "project-id" along with "type"

Request

{
  "event" : {
    "start" : "YYYY-MM-DDThh:mm:ss",
    "end" : "YYYY-MM-DDThh:mm:ss",
    "all-day" : "true/false",
    "title" : "Some event title",
    "description" : "Some event description (optional)",
    "where" : "Some location (optional)",
    "privacy" : {
        "type" : "company"
    },
    "project-id" : "0",
    "show-as-busy":"true/false",
    "type" : {
      "id" : "numeric calendarEventType id"
    },
    "attending-user-ids":"comma separated list of user id's",
    "notify-user-ids":"comma separated list of user id's",
    "notify":"false",
    "attendees-can-edit":"true/false",
    "project-users-can-edit":"true/false",
    "reminders" : [
      {
        "type":"string (one of the following sms,email,push)",
        "period":"string (one of the following minutes,hours,days,weeks)",
        "before":"numeric value (e.g: 15)"
      }  
    ]
  }
}

Response

Returns a HTTP status code of 201 for "Created" on success.


Delete event

DELETE /calendarevents/{id}.json

Deletes the calendar event.

Response

Returns HTTP status code 200 on success.


Get event types

GET /calendareventtypes.json

Returns details about event types.

GET /eventtypes.json

Request

{
  "eventtypes": [
    {
      "name": "Birthdays",
      "id": "100021",
      "color": "ABAE15"
    },
    :
    :
  ],
  "STATUS": "OK"
}


Create an Event Type

Post to /eventtypes.json

Request

{
	"eventtype": {
		"name": "new event type",
		"color": "526D45"
	}
}

Response

{"id":"1","STATUS":"OK"}


Delete an Event Type

DELETE to /eventtypes/{event_type_id}.json

Response

{"STATUS":"OK"}


Edit an Event Type

To update an existing Event Type

Perform a PUT to /eventtypes/{event_type_id}.json

Request

{
	"eventtype": {
		"name": "updated event type name",
		"color": "526D45",
		"id": "{event_type_id}"
	}
}

Response

{"STATUS":"OK"}