API Reference

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

Data
Please URL encode all parameter values. Your API token is: .

JOB List calendars

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

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

Example with data

https://www.calendarx.com/api/v1/calendars/list/?token=

Returns

{
	"meta": {
		"code": "200"
	},
	"calendars": [{
		"id": "145161006114",
		"uniquekey": "ic14",
		"calendarname": "Demo Calendar",
		"title": "Follow our calendar",
		"description": "Follow our calendar and stay up to date with our events. Once you have subscribed our events will automatically appear in your calendar application or mobile device.",
		"timezone": "America\/Los_Angeles",
		"followers_active": "805",
		"followers_total": "1427",
		"events_total": "100",
		"palette_id": "aBFTf11",
		"date_create": 1434422899,
		"date_modified": 1477958407
	}],
	"paging": {
		"previous": "",
		"next": "https:\/\/www.calendarx.com\/api\/v1\/calendars\/list\/?token=&page=2"
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.

JOB Create a calendar

Creates a calendar. Returns the calendar created.

$ curl https://www.calendarx.com/api/v1/calendars/create/?token=token&calendarname=calendarname&title=title&description=description&timezone=timezone&palette_id=palette_id

Example with data

https://www.calendarx.com/api/v1/calendars/create/?token=&calendarname=Name+of+calendar&title=Follow+our+calendar&description=Description+of+calendar&timezone=America/Los_Angeles&palette_id=aBFTf11

Returns

{
	"meta": {
		"code": "200"
	},
	"calendar": {
		"id": "14793391331949",
		"uniquekey": "XC1949",
		"calendarname": "Name of calendar",
		"title": "Follow our calendar",
		"description": "Description of calendar",
		"timezone": ""America\/Los_Angeles"",
		"followers_active": "0",
		"followers_total": "0",
		"events_total": "0",
		"palette_id": "aBFTf11",
		"date_create": 1479339133,
		"date_modified": 1479339133
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendarname
Calendar name of the calendar. If parameter doesn't contain a value, the title is used as calendarname.
title
Mandatory   Title of the calendar.
timezone
Mandatory   Time zone of the calendar. If the timezone parameter doesn't contain a value, the timezone "America/Los_Angeles" is used.
palette_id
ID of the color palette to use in the calendar. If the palette_id parameter doesn't contain a value, the calendar will use the "CalendarX default" color palette.

JOB Save a calendar

Save a calendar. Returns the calendar saved.

$ curl https://www.calendarx.com/api/v1/calendars/save/?token=token&calendarname=calendarname&title=title&description=description&timezone=timezone&palette_id=palette_id&calendar_id=calendar_id

Example with data

https://www.calendarx.com/api/v1/calendars/save/?token=&calendarname=Name+of+calendar&title=Follow+our+calendar&description=Description+of+calendar&timezone=America/Los_Angeles&palette_id=aBFTf11&calendar_id=14793391331949

Returns

{
	"meta": {
		"code": "200"
	},
	"calendar": {
		"id": "14793391331949",
		"uniquekey": "XC1949",
		"calendarname": "Name of calendar",
		"title": "Follow our calendar",
		"description": "Description of calendar",
		"followers_active": "0",
		"followers_total": "0",
		"events_total": "0",
		"palette_id": "aBFTf11",
		"date_create": 1479339133,
		"date_modified": 1479342638
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendarname
Calendar name of the calendar. If parameter doesn't contain a value, the title is used as calendarname.
title
Mandatory   Title of the calendar.
timezone
Mandatory   Time zone of the calendar. If the timezone parameter doesn't contain a value, the timezone "America/Los_Angeles" is used.
palette_id
ID of the color palette to use in the calendar. If the palette_id parameter doesn't contain a value, the calendar will use the "CalendarX default" color palette.
calendar_id
Mandatory   Id of the calendar to save.

JOB Delete a calendar

Delete a calendar. Returns a deletion status.

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

Example with data

https://www.calendarx.com/api/v1/calendars/delete/?token=&calendar_id=14793391331949

Returns

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

Parameters

Parameter
Description
token
Mandatory   Account token.
calendar_id
Mandatory   Id of the calendar to delete.

JOB List events in a calendar

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

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

Example with data

https://www.calendarx.com/api/v1/calendars/events/list/?token=&calendar_id=1473327868906

Returns

{
	"meta": {
		"code": "200"
	},
	"calendar": {
		"id": "1473327868906",
		"events_count": 33
	},
	"events": [{
		"id": "125163",
		"title": "Cookie Fridays",
		"description": "The oven is hot and our cookies are ready to be served :-)\r\n\r\nInclude a link to direct users to: http:\/\/www.example.com\/cookies\r\n\r\nToday's special is Cinnamon Spice stuffed with White Chocolate Chip.\r\n\r\nStop by before 12pm and get yours! Buy one, get one free to all followers.",
		"location": "1416 Valencia St, San Francisco, CA 94110",
		"organizer": "",
		"organizer_email": "",
		"date_start": "04\/21\/2017",
		"date_start_time": "15:00:00",
		"date_start_ampm": "PM",
		"date_start_unix": 1492786800,
		"date_end": "04\/21\/2017",
		"date_end_time": "16:00:00",
		"date_end_ampm": "PM",
		"date_end_unix": 1492790400,
		"all_day_event": "false",
		"date_format": "MM\/DD\/YYYY",
		"timezone": "America\/Los_Angeles",
		"color": "1",
		"reminder": "15",
		"date_create": 1473984345,
		"date_modified": 1473984345,
		"updated_times": "0"
	}, {
		"id": "125162",
		"title": "Cookie Fridays",
		"description": "The oven is hot and our cookies are ready to be served :-)\r\n\r\nInclude a link to direct users to: http:\/\/www.example.com\/cookies\r\n\r\nToday's special is Cinnamon Spice stuffed with White Chocolate Chip.\r\n\r\nStop by before 12pm and get yours! Buy one, get one free to all followers.",
		"location": "1416 Valencia St, San Francisco, CA 94110",
		"organizer": "",
		"organizer_email": "",
		"date_start": "04\/14\/2017",
		"date_start_time": "15:00:00",
		"date_start_ampm": "PM",
		"date_start_unix": 1492182000,
		"date_end": "04\/14\/2017",
		"date_end_time": "16:00:00",
		"date_end_ampm": "PM",
		"date_end_unix": 1492185600,
		"all_day_event": "false",
		"date_format": "MM\/DD\/YYYY",
		"timezone": "America\/Los_Angeles",
		"color": "1",
		"reminder": "15",
		"date_create": 1473984345,
		"date_modified": 1473984345,
		"updated_times": "0"
	}],
	"paging": {
		"previous": "",
		"next": "https:\/\/www.calendarx.com\/api\/v1\/calendars\/events\/list\/?token=&calendar_id=1473327868906&page=2"
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendar_id
Mandatory   Id of the calendar.
order_by
List events in the calendar in a specific order.
Accepts: "date-desc" 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. Please notice: This parameter disables "order_by". Accepts: "now" or a date/time. Date/time can be the following format: "2018-11-31 12:01:00" or "31-11-2018 12:01:00" or "2018/11/31 12:01pm" or "11/31/2018 12:01pm".

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

JOB Create event in a calendar

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

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

Example with data

https://www.calendarx.com/api/v1/calendars/events/create/?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=America/Los_Angeles&color_id=1&reminder=60&start_date=12%2F15%2F2024+09%3A00&end_date=12%2F15%2F202411%3A00&all_day_event=false

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": ""12\/15\/2024"",
		"date_start_time": "09:00:00",
		"date_start_ampm": "AM",
		"date_end": ""12\/15\/2024"",
		"date_end_time": "11:00:00",
		"date_end_ampm": "AM",
		"all_day_event": "false",
		"date_format": "MM\/DD\/YYYY",
		"timezone": ""America\/Los_Angeles"",
		"color_id": "1",
		"reminder": "60",
		"updated_times": "0",
		"date_create": 1479434024,
		"date_modified": 1479434024
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendar_id
Mandatory   Id of the calendar.
title
Mandatory   Title of the event
description
Description of the event. Use \n for line breaks.
location
Location of the event, e.g. "1600 Amphitheatre Pkwy, Mountain View, CA 94043".
organizer
Organizer of the event, e.g. "Thomas Scott".
organizer_email
Organizer's email, e.g. "thomas@example.com"
timezone
Time zone of the event, e.g. "America/Los_Angeles". View "Timezones" for all time zones available. Uses calendars default time zone if not defined.
color_id
Color ID (number 1-20) to use from the color palette. The color palette attached to the calendar can contain up to 20 colors. Uses no color if the color ID is not defined.
reminder
Set an event reminder. Value is in minutes, e.g. "5" or "10" or "60" or "120" minutes.
start_date
Mandatory   Start date of the event. Accepts numeric dates, e.g. "12/15/2024 09:00" or "12/15/2024 09:00 AM". Accepted format of date: "MM/DD/YYYY HH:MM".
end_date
End date of the event. Accepts numeric dates, e.g. "12/15/2024 11:00" or "12/15/2024 11:00 AM". Accepted format of date: "MM/DD/YYYY HH:MM". If end_date isn't defined, end_date becomes start_date plus 1 hour.
all_day_event
All day event. Defaults to "false". Accepts "true" or "false".

JOB Save event in a calendar

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

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

Example with data

https://www.calendarx.com/api/v1/calendars/events/save/?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=America/Los_Angeles&color_id=1&reminder=60&start_date=12%2F15%2F2024+09%3A00&end_date=12%2F15%2F202411%3A00&all_day_event=false

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": ""12\/15\/2024"",
		"date_start_time": "09:00:00",
		"date_start_ampm": "AM",
		"date_end": ""12\/15\/2024"",
		"date_end_time": "11:00:00",
		"date_end_ampm": "AM",
		"all_day_event": "false",
		"date_format": "MM\/DD\/YYYY",
		"timezone": ""America\/Los_Angeles"",
		"color_id": "1",
		"reminder": "60",
		"updated_times": "1",
		"date_create": 1479434024,
		"date_modified": 1479434024
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
event_id
Mandatory   Id of the event.
title
Mandatory   Title of the event
description
Description of the event. Use \n for line breaks.
location
Location of the event, e.g. "1600 Amphitheatre Pkwy, Mountain View, CA 94043".
organizer
Organizer of the event, e.g. "Thomas Scott".
organizer_email
Organizer's email, e.g. "thomas@example.com"
timezone
Time zone of the event, e.g. "America/Los_Angeles". View "Timezones" for all time zones available. Uses calendars default time zone if not defined.
color_id
Color ID (number 1-20) to use from the color palette. The color palette attached to the calendar can contain up to 20 colors. Uses no color if the color ID is not defined.
reminder
Set an event reminder. Value is in minutes, e.g. "5" or "10" or "60" or "120" minutes.
start_date
Mandatory   Start date of the event. Accepts numeric dates, e.g. "12/15/2024 09:00" or "12/15/2024 09:00 AM". Accepted format of date: "MM/DD/YYYY HH:MM".
end_date
End date of the event. Accepts numeric dates, e.g. "12/15/2024 11:00" or "12/15/2024 11:00 AM". Accepted format of date: "MM/DD/YYYY HH:MM". If end_date isn't defined, end_date becomes start_date plus 1 hour.
all_day_event
All day event. Defaults to "false". Accepts "true" or "false".

JOB Delete event in a calendar

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

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

Example with data

https://www.calendarx.com/api/v1/calendars/events/delete/?token=&event_id=159051

Returns

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

Parameters

Parameter
Description
token
Mandatory   Account token.
event_id
Mandatory   Id of the event.

JOB List calendar subscribers

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

$ curl https://www.calendarx.com/api/v1/calendars/subscribers/list/?token=token&calendar_id=calendar_id

Example with data

https://www.calendarx.com/api/v1/calendars/subscribers/list/?token=&calendar_id=1473327868906

Returns

{
	"meta": {
		"code": "200"
	},
	"calendar": {
		"id": "1473327868906",
		"subscribers_count": 33
	},
	"subscribers": [{
		"id": "czekb1517288022tfolxp",
		"name": "Michael Nilsson",
		"email": "michael@addevent.com",
		"ip": "182.232.234.219",
		"postal": "94401",
		"city": "San Mateo",
		"state": "CA",
		"country": "US",
		"date": "01\/30\/2018 04:57:02",
		"unixtime_stamp": 1517284622,
		"calendar_type": "google",
		"active": "true",
		"blocked": "false"
	},{
		"id": "utnlw1517085906ufrpt8",
		"name": "Constantin Simoni",
		"email": "email@example.com",
		"ip": "85.255.232.245",
		"postal": "null",
		"city": "null",
		"state": "null",
		"country": "ES",
		"date": "01\/28\/2018 12:01:10",
		"unixtime_stamp": 1527284622,
		"calendar_type": "outlookcom",
		"active": "true",
		"blocked": "false"
	}],
	"paging": {
		"previous": "",
		"next": "https:\/\/www.calendarx.com\/api\/v1\/calendars\/subscribers\/list\/?token=&calendar_id=1473327868906&page=2"
	}
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendar_id
Mandatory   Id of the calendar.
order_by
List subscribers to the calendar in a specific order.
Accepts: "date-desc" or "date-desc" or "id-asc" or "id-desc"

Example: "&order_by=date-desc"
month + year
List subscribers to 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"
inactive
List inactive subscribers only by including "inactive" in the path, e.g. .../api/v1/calendars/subscribers/list/inactive/?token=....
blocked
List blocked subscribers only by including "blocked" in the path, e.g. .../api/v1/calendars/subscribers/list/blocked/?token=....

JOB Details about a subscriber

Returns details about a subscriber.

$ curl https://www.calendarx.com/api/v1/calendars/subscriber/?token=token&calendar_id=calendar_id&subscriber_id=subscriber_id

Example with data

https://www.calendarx.com/api/v1/calendars/subscriber/?token=&calendar_id=1473327868906&subscriber_id=czekb1517288022tfolrt

Returns

{
	"meta": {
		"code": "200"
	},
	"calendar": {
		"id": "1473327868906"
	},
	"subscribers": [{
		"id": "czekb1517288022tfolxp",
		"name": "Michael Nilsson",
		"email": "michael@addevent.com",
		"ip": "182.232.234.219",
		"postal": "94401",
		"city": "San Mateo",
		"state": "CA",
		"country": "US",
		"date": "01\/30\/2018 04:57:02",
		"unixtime_stamp": 1517284622,
		"calendar_type": "google",
		"active": "true",
		"blocked": "false"
	}]
}

Parameters

Parameter
Description
token
Mandatory   Account token.
calendar_id
Mandatory   Id of the calendar.
subscriber_id
Mandatory   Id of the subscriber.

JOB List of time zones

Lists all available time zones.

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

Returns

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