Documentation
CalMonkey gives your product one API for your users’ Google Calendar, Microsoft 365, Outlook.com and Apple iCloud calendars. Your users connect on a hosted page, and your server reads free/busy and events, writes events (with guests, repeats and meeting links) and gets told about changes. New here? Go to the quickstart.
Start here
- QuickstartConnect a calendar, exchange the code, list calendars, read free/busy, write an event and receive webhooks.
- API referenceEvery endpoint with its parameters, request and response, including guests, repeating events and meeting links.
- Errors and limitsError shapes, rate limits, request ids and the webhook retry schedule.
- ProvidersGoogle, Microsoft 365, Outlook.com and Apple iCloud: what each needs, what each does with guests and meeting links, and how fresh the data is.
- Migrating from CronofyCompatibility mode, what differs, and the steps to switch.
Hostnames
CalMonkey answers on two hostnames. Every example in these pages uses them as they are.
| Host | What is there |
|---|---|
https://api.calmonkey.com | The API: /oauth/token, /oauth/token/revoke and everything under /v1. Your server calls it. |
https://app.calmonkey.com | What people see in a browser: /oauth/authorize and the hosted connect pages your users go through, and the dashboard at /dashboard where you manage your applications. |
If you are moving from Cronofy, the API host takes the place of api.cronofy.com and the app host the place of app.cronofy.com. See Migrating from Cronofy.
How the pieces fit
- Application
- Your product, as CalMonkey knows it. It has a client id, a client secret and the redirect URIs your users may be sent back to. You create applications in the dashboard (sign in at app.calmonkey.com/sign-in). The client secret is shown once, when it is created or rotated: store it in your secret manager.
- Account
- One of your users (
acc_…). Your application gets an account, with an access token and a refresh token, when a user connects a calendar through the hosted connect page. Its id comes back assub. - Profile
- One calendar account the user connected (
pro_…): a Google account, a Microsoft 365 or Outlook.com mailbox, or an Apple ID. An account can have several. - Calendar
- A calendar of a profile (
cal_…). You read free/busy and events from calendars and write events to the ones that are not read-only. - Event
- Something in a calendar. Your application writes events under its own
event_id: a single event or a repeating one, with guests the calendar invites for you and a meeting link the calendar adds. Reads return every event in the calendar, with its guests and their replies. - Application calendar
- A calendar CalMonkey hosts itself (
apc_…accounts), opened with your client credentials alone. Use them for tests and demos, or for people who have no calendar to connect. - Channel
- A webhook subscription (
chn_…): CalMonkey sends a signed notification to your callback URL when something changes in an account’s calendars.
Conventions
- Requests and responses are JSON. Field names are snake_case, and the same as Cronofy’s for the endpoints both have.
/v1endpoints takeAuthorization: Bearer <access_token>. Access tokens last 3 hours; refresh them with the refresh token, which does not change.- Times are ISO 8601 with an offset, returned in UTC unless you ask for local times. All-day events are dates, and their end date is exclusive.
- Every response carries a
Calmonkey-Request-Idheader. Quote it when you write to support@calmonkey.com. - Event writes answer
202 Acceptedwith an empty body. The event shows in free/busy and event reads straight away; the write to Google, Microsoft or iCloud follows in the background.