Calendar API

The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. All API access is over HTTPS. All data is received as JSON, including errors.

Data
Please URL encode all parameter values.

The API requires an API token to work.
Please sign in or create an account to receive your accounts API tokens.

List calendars

Returns a list of calendars. The calendars are sorted by recently saved calendars appearing first.

$ curl https://www.addevent.com/api/v1/me/calendars/list/?token=token

$ curl https://www.addevent.com/api/v1/me/calendars/list/?token=API-TOKEN

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "calendars": [{
									       "id": "145161006114",
									       "uniquekey": "ic14",
									       "title": "Add our events to your calendar",
									       "description": "Select your calendar, and accept the calendar subscription notice. \n\nWhen accepted, all of our events will automatically appear in your calendar application or mobile device.",
									       "followers_active": "805",
									       "followers_total": "1427",
									       "events_total": "100",
									       "main_calendar": "false",
									       "date_create": 1434422899,
									       "date_modified": 1477958407
									   }],
									   "paging": {
									       "previous": "",
									       "next": "https:\/\/www.addevent.com\/api\/v1\/me\/calendars\/list\/?token=API-TOKEN&page=2"
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

Create a calendar

Creates a calendar. Returns the calendar created.

$ curl https://www.addevent.com/api/v1/me/calendars/create/?token=token&title=title&description=description

$ curl https://www.addevent.com/api/v1/me/calendars/create/?token=API-TOKEN&title=Add+our+events+to+your+calendar&description=Select+your+calendar%2C+and+accept+the+calendar+subscription+notice.+%0A%0AWhen+accepted%2C+all+of+our+events+will+automatically+appear+in+your+calendar+application+or+mobile+device.

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "calendar": {
									       "id": "14793391331949",
									       "uniquekey": "XC1949",
									       "title": "Add our events to your calendar",
									       "description": "Select your calendar, and accept the calendar subscription notice. \n\nWhen accepted, all of our events will automatically appear in your calendar application or mobile device.",
									       "followers_active": "0",
									       "followers_total": "0",
									       "events_total": "0",
									       "date_create": 1479339133,
									       "date_modified": 1479339133
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

title

Required

Title of the event. Single line string.

description

Description of the calendar. Use \n to separate lines. The field accepts plain text.

The description is used on the calendars subscribe page, e.g. https://www.addevent.com/calendar/ic14.

Save a calendar

Save a calendar. Returns the calendar saved.

$ curl https://www.addevent.com/api/v1/me/calendars/save/?token=token&title=title&description=description&calendar_id=calendar_id

$ curl https://www.addevent.com/api/v1/me/calendars/save/?token=API-TOKEN&title=Add+our+events+to+your+calendar&description=Select+your+calendar%2C+and+accept+the+calendar+subscription+notice.+%0A%0AWhen+accepted%2C+all+of+our+events+will+automatically+appear+in+your+calendar+application+or+mobile+device.&calendar_id=14793391331949

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "calendar": {
									       "id": "14793391331949",
									       "uniquekey": "XC1949",
									       "title": "Add our events to your calendar",
									       "description": "Select your calendar, and accept the calendar subscription notice. \n\nWhen accepted, all of our events will automatically appear in your calendar application or mobile device.",
									       "followers_active": "0",
									       "followers_total": "0",
									       "events_total": "0",
									       "date_create": 1479339133,
									       "date_modified": 1479342638
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

calendar_id

Required

Id of the calendar to save.

title

Required

Title of the event. Single line string.

description

Description of the calendar. Use \n to separate lines. The field accepts plain text.

The description is used on the calendars subscribe page, e.g. https://www.addevent.com/calendar/ic14.

Delete a calendar

Delete a calendar. Returns a deletion status. Please notice. A "main calendar" can't be deleted.

$ curl https://www.addevent.com/api/v1/me/calendars/delete/?token=token&calendar_id=calendar_id

$ curl https://www.addevent.com/api/v1/me/calendars/delete/?token=API-TOKEN&calendar_id=14793391331949

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "calendar": {
									       "id": "14793391331949",
									       "status": "deleted"
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

calendar_id

Required

Id of the calendar to delete.

List events in a calendar

Returns a list of events in a calendar. The events are sorted by recently created.

$ curl https://www.addevent.com/api/v1/me/calendars/events/list/?token=token&calendar_id=calendar_id

$ curl https://www.addevent.com/api/v1/me/calendars/events/list/?token=API-TOKEN&calendar_id=1473327868906

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "calendar": {
									       "id": "1473327868906",
									       "events_count": 33
									   },
									   "events": [{
									       "id": "125163",
									       "title": "Title of the event",
									       "eventname": "Title of the event",
									       "description": "Description of the event",
									       "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
									       "organizer": "Thomas Scott",
									       "organizer_email": "thomas@example.com",
									       "date_start": "05\/21\/2020",
									       "date_start_time": "09:00:00",
									       "date_start_ampm": "AM",
									       "date_start_unix": 1590051600,
									       "date_end": "05\/21\/2020",
									       "date_end_time": "11:00:00",
									       "date_end_ampm": "AM",
									       "date_end_unix": 1590058800,
									       "all_day_event": "false",
									       "date_format": "MM\/DD\/YYYY",
									       "timezone": "",
									       "reminder": "60",
									       "custom_data": "%7B%22name%22%3A%22Michael%22%2C%22bannerimage%22%3A%22https%3A%2F%2Fexample.org%2F...%2Fbanner1.jpg%22%7D",
									       "date_create": 1590051600,
									       "date_modified": 1590051600,
									       "updated_times": "0"
									   }, {
									       "id": "125162",
									       "title": "Title of the event",
									       "eventname": "Title of the event",
									       "description": "Description of the event",
									       "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
									       "organizer": "Thomas Scott",
									       "organizer_email": "thomas@example.com",
									       "date_start": "05\/14\/2020",
									       "date_start_time": "09:00:00",
									       "date_start_ampm": "AM",
									       "date_start_unix": 1589446800,
									       "date_end": "05\/14\/2020",
									       "date_end_time": "11:00:00",
									       "date_end_ampm": "AM",
									       "date_end_unix": 1589454000,
									       "all_day_event": "false",
									       "date_format": "MM\/DD\/YYYY",
									       "timezone": "",
									       "reminder": "60",
									       "custom_data": "%7B%22name%22%3A%22Michael%22%2C%22bannerimage%22%3A%22https%3A%2F%2Fexample.org%2F...%2Fbanner1.jpg%22%7D",
									       "date_create": 1589446800,
									       "date_modified": 1589446800,
									       "updated_times": "0"
									   }],
									   "paging": {
									       "previous": "",
									       "next": "https:\/\/www.addevent.com\/api\/v1\/me\/calendars\/events\/list\/?token=API-TOKEN&calendar_id=1473327868906&page=2"
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

calendar_id

Required

Id of the calendar.

order_by

List events in the calendar in a specific order.
Accepts: date-asc or date-desc or id-asc or id-desc

Example: &order_by=date-desc

month + year

List events in the calendar in a specific month of the year.
Accepts: month combined with year. Month must contain two digits (from 01-12) and year must contain four digits, e.g. "2018".

Example: &month=06&year=2018

upcoming

List upcoming events in the calendar from "now" or from a specific date/time value. Please notice: This parameter set "order_by" to "date-asc" by default. Accepts: now or a date/time. Date/time can be the following format: "2018-11-31 17:30:00" or "31-11-2018 11:00:00" or "2018/11/31 09:37am" or "11/31/2018 03:05pm".

Example: &upcoming=now" or "&upcoming=2018/11/31 12:01pm

Create an event in a calendar

Creates an event in a calendar. Returns the event created.

$ curl https://www.addevent.com/api/v1/me/calendars/events/create/?token=token&calendar_id=calendar_id&title=title&description=description&location=location&organizer=organizer&organizer_email=organizer_email&timezone=timezone&reminder=reminder&start_date=start_date&end_date=end_date&all_day_event=all_day_event&custom_data=custom_data

$ curl https://www.addevent.com/api/v1/me/calendars/events/create/?token=API-TOKEN&calendar_id=1473327868906&title=Title+of+the+event&description=Description+of+the+event&location=1600+Amphitheatre+Pkwy%2C+Mountain+View%2C+CA+94043&organizer=Thomas+Scott&organizer_email=thomas%40example.com&timezone=%3C%3Fphp+echo+%3B+%3F%3E&reminder=60&start_date=06%2F16%2F2020+09%3A00&end_date=06%2F16%2F202011%3A00&all_day_event=false&custom_data="{\"name\":\"Michael\",\"bannerimage\":\"https:\/\/example.org\/...\/banner1.jpg\"}"

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "event": {
									       "id": 159051,
									       "calendar": "1473327868906",
									       "title": "Title of the event",
									       "description": "Description of the event",
									       "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
									       "organizer": "Thomas Scott",
									       "organizer_email": "thomas@example.com",
									       "date_start": "06\/16\/2020",
									       "date_start_time": "09:00:00",
									       "date_start_ampm": ""AM"",
									       "date_end": "06\/16\/2020",
									       "date_end_time": "11:00:00",
									       "date_end_ampm": ""AM"",
									       "all_day_event": "false",
									       "date_format": "MM\/DD\/YYYY",
									       "timezone": "",
									       "reminder": "60",
									       "custom_data": ""{\"name\":\"Michael\",\"bannerimage\":\"https:\/\/example.org\/...\/banner1.jpg\"}"",
									       "updated_times": "0",
									       "date_create": 1592298000,
									       "date_modified": 1592298000 
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

calendar_id

Required

Id of the calendar to create the event in.

title

Required

Title of the event. Single line string.

description

Description of the event. Use \n to separate lines. The field accepts plain text.

location

Location of the event, e.g. "1600 Amphitheatre Pkwy, Mountain View, CA 94043".

organizer

Event organizer, e.g. "Thomas Scott".

If you fill out organizer you must also include the organizer_email field.

If you include an organizer and an organizer_email, the event is considered to be a "meeting" by calendar clients like Outlook. If you don't include the fields, the event is considered to be an "appointment".

organizer_email

Event organizer e-mail, e.g. "thomas@example.com".

If you fill out organizer_email you must also include the organizer field.

If you include an organizer and an organizer_email, the event is considered to be a "meeting" by calendar clients like Outlook. If you don't include the fields, the event is considered to be an "appointment".

timezone

Required

The events time zone, e.g. Europe/Paris or .

The timezone parameter converts the date/time to Zulu time / GMT / UTC. The timezone parameter defaults to "" if a timezone is not defined.

You can find a list of all time zones (Section: List of time zones) at the bottom of this page.

Explanation: The timezone parameter makes sure the date/time is correct no matter if you are in New York or Sydney.

reminder

Event reminder. Trigger an event reminder e.g. "15" minutes before the event starts.
Accepted input: Number

Example: Reminder "15" minutes before event starts = 15 or
one day before event starts : 60 minutes x 24 hours = 1440.

Event reminders are currently supported by:
- Apple Calendar
- Outlook

start_date

Required

Start date of the event. Accepts most date/time formats, e.g. 06/02/2020 03:00 PM (12-hour format) or 02-06-2020 15:00 (24-hour format).

Use numeric values to describe the date, e.g. "06/16/2020" and not textual, e.g. "June 16th, 2020".

Dates in the m/d/y or d-m-y formats are disambiguated by looking at the separator between the various components: if the separator is a slash (/), then the American m/d/y is assumed; whereas if the separator is a dash (-) or a dot (.), then the European d-m-y format is assumed. If, however, the year is given in a two digit format and the separator is a dash (-, the date string is parsed as y-m-d. To avoid potential ambiguity, it's best to use ISO 8601 (YYYY-MM-DD) dates

Date examples:
06/02/2020 03:00 PM or 02-06-2020 15:00 or 2020/06/02 03:00 PM or 2020-06-02 15:00

end_date

End date of the event. Accepts most date/time formats, e.g. 06/02/2020 05:00 PM (12-hour format) or 02-06-2020 17:00 (24-hour format).

Use numeric values to describe the date, e.g. "06/16/2020" and not textual, e.g. "June 16th, 2020".

Dates in the m/d/y or d-m-y formats are disambiguated by looking at the separator between the various components: if the separator is a slash (/), then the American m/d/y is assumed; whereas if the separator is a dash (-) or a dot (.), then the European d-m-y format is assumed. If, however, the year is given in a two digit format and the separator is a dash (-, the date string is parsed as y-m-d. To avoid potential ambiguity, it's best to use ISO 8601 (YYYY-MM-DD) dates

Date examples:
06/02/2020 05:00 PM or 02-06-2020 17:00 or 2020/06/02 05:00 PM or 2020-06-02 17:00

If end is not defined, the end date is automatically set to start date plus one hour.

all_day_event

All day event. Accepts true or false.

custom_data

Allows you to save a JSON string containing keys and values which can be used with a custom event templates.

E.g. {"name":"Michael","bannerimage":"https://example.org/.../banner1.jpg"}

The system will collect the keys in the JSON string and make the keys/values available in the template markup.

E.g. use {{name}} or {{bannerimage}} to output the variables in your custom template.

Requires valid JSON. Max length of JSON string is 500 characters.

Save an event in a calendar

Save an event in a calendar. Returns the event saved.

$ curl https://www.addevent.com/api/v1/me/calendars/events/save/?token=token&event_id=event_id&title=title&description=description&location=location&organizer=organizer&organizer_email=organizer_email&timezone=timezone&reminder=reminder&start_date=start_date&end_date=end_date&all_day_event=all_day_event&custom_data=custom_data

$ curl https://www.addevent.com/api/v1/me/calendars/events/save/?token=API-TOKEN&event_id=159051&title=Title+of+the+event&description=Description+of+the+event&location=1600+Amphitheatre+Pkwy%2C+Mountain+View%2C+CA+94043&organizer=Thomas+Scott&organizer_email=thomas%40example.com&timezone=%3C%3Fphp+echo+%3B+%3F%3E&reminder=60&start_date=06%2F16%2F2020+09%3A00&end_date=06%2F16%2F202011%3A00&all_day_event=false&custom_data=%7B%22name%22%3A%22Michael%22%2C%22bannerimage%22%3A%22https%3A%2F%2Fexample.org%2F...%2Fbanner1.jpg%22%7D

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "event": {
									       "id": 159051,
									       "calendar": "1473327868906",
									       "title": "Title of the event",
									       "description": "Description of the event",
									       "location": "1600 Amphitheatre Pkwy, Mountain View, CA 94043",
									       "organizer": "Thomas Scott",
									       "organizer_email": "thomas@example.com",
									       "date_start": "06\/16\/2020",
									       "date_start_time": "09:00:00",
									       "date_start_ampm": "AM",
									       "date_end": "06\/16\/2020",
									       "date_end_time": "11:00:00",
									       "date_end_ampm": "AM",
									       "all_day_event": "false",
									       "date_format": "MM\/DD\/YYYY",
									       "timezone": "",
									       "reminder": "60",
									       "custom_data": ""{\"name\":\"Michael\",\"bannerimage\":\"https:\/\/example.org\/...\/banner1.jpg\"}"",
									       "updated_times": "1",
									       "date_create": 1592298000,
									       "date_modified": 1592298000 
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

event_id

Required

Id of the event to save.

title

Required

Title of the event. Single line string.

description

Description of the event. Use \n to separate lines. The field accepts plain text.

location

Location of the event, e.g. "1600 Amphitheatre Pkwy, Mountain View, CA 94043".

organizer

organizer_email

timezone

reminder

start_date

end_date

all_day_event

All day event. Accepts true or false.

custom_data

Delete an event in a calendar

Deletes an event in a calendar. Returns a deletion status.

$ curl https://www.addevent.com/api/v1/me/calendars/events/delete/?token=token&event_id=event_id

$ curl https://www.addevent.com/api/v1/me/calendars/events/delete/?token=API-TOKEN&event_id=159051

Returns

{
									   "meta": {
									       "code": "200"
									   },
									   "event": {
									       "id": "159051",
									       "status": "deleted"
									   }
									}

Parameter

Description

token

Required

Account token. The account token is available in the Account section and is incorporated in all code examples on this page.

event_id

Required

Id of the event to delete.

List of time zones

Lists of all available time zones.

cURL

$ curl https://www.addevent.com/api/v1/timezones

Returns

{
									   "meta": {
									       "code": 200
									   },
									   "data": [{
									       "label": "Africa/Abidjan",
									       "offset": "00:00"
									   }, {
									       "label": "Africa/Accra",
									       "offset": "00:00"
									   },
									   {
									       etc.
									   }]
									}