Real-Time Scheduling

Required plan: Emerging

Description #

Returns a URL to a form where a user can select their preferred date and time for an event based upon live availability information.

URL format #


Example Request #

POST /v1/real_time_scheduling HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

  "oauth": {
    "redirect_uri": "{REDIRECT_URI}",
  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "summary": "Product Manager Interview at Globex",
    "tzid": "Europe/London"
  "availability": {
    "participants": [
        "members": [
            "sub": "acc_567236000909002",
            "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"]
        "required": "all"
    "required_duration": { "minutes": 60 },
    "query_periods": [
      { "start": "2022-01-20T09:00:00Z", "end": "2022-01-20T18:00:00Z" }
  "target_calendars": [
      "sub": "acc_567236000909002",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234"
  "callback_url": "",
  "redirect_urls": {
    "completed_url": ""

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

  "real_time_scheduling": {
    "real_time_scheduling_id": "sch_4353945880944395",

Request parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • - πŸ‡¦πŸ‡Ί Australia
  • - πŸ‡¨πŸ‡¦ Canada
  • - πŸ‡©πŸ‡ͺ Germany
  • - πŸ‡ΈπŸ‡¬ Singapore
  • - πŸ‡¬πŸ‡§ United Kingdom
  • - πŸ‡ΊπŸ‡Έ United States

Find out more about Cronofy's data centers.

API_KEY required  #

The client_secret of the client.

oauth.redirect_uri required  #

The HTTP or HTTPS URI you wish the user to be redirected to after their Real-Time Scheduling journey.

event required  #

An object with the details of the event you wish to push into the user’s selected calendar. Details of what parameters this object can hold can be found in the create or update event documentation.

Note - event.attendees are only supported when event_creation is set to single.

event.tzid required  #

The timezone to render the event with.

The start and end parameters should be omited.

availability required  #
An object with the details of the availability query used to determine the available time periods for the user to choose for the event’s date and time. Details of what parameters this object can hold can be found in the Availability documentation.

event_creation optional BETA  #

One of two values:

  • default or omitted - creates an event in each calendar listed in the target_calendars list.
  • single - creates an event in one target calendar - if multiple target_calendars are a match for the selected slot, then the order of the participants in the availability query is used to choose the preferred calendar.

You can use this capability along with event.attendees to set a primary event owner and set all other people as event attendees.

target_calendars optional  #

An array of Cronofy sub values and calendar ids into which the final event will be inserted.

formatting.hour_format optional  #

An String of either h (12-hour format) or H (24-hour format). If omitted then the hour format to use will be determined by Cronofy.

callback_url optional  #

A URL to call when the full event details are known.

redirect_urls.completed_url optional  #

A URL to redirect the user to when the user has completed the process and chosen a slot.

A query string parameter of token will be added to this URL. The token can be used to retrieve the current status of a Real Time Scheduling link.

availability.start_interval optional  #

A Duration describing the frequency that a sequence can start on.

For example, “every hour” or “every 15 minutes”.

Must be an increment of one of 5, 10, 15, 20, 30, or 60 minutes.

By default Real Time Scheduling will use the required duration to derive the interval of slots. For example, 60 minute slots will begin on the hour

  • 9:00am – 10:00am
  • 10:00am – 11:00am
  • 11:00am – 12:00pm

This works well when a calendar is mostly free, however if an hour-long meeting at 9:30am - 10:30am is scheduled we would only have the 11am slot available.

  • 9:00am – 10:00am
  • 10:00am – 11:00am
  • 11:00am – 12:00pm

To avoid this problem, we can set the slots to begin every 30 minutes for the same period of time would mean the following would be selectable.

  • 9:00am – 10:00am
  • 9:30am – 10:30am
  • 10:00am – 11:00am
  • 10:30am – 11:30am
  • 11:00am – 12:00pm
minimum_notice optional  #

A Duration. No slots starting before the period described after the current time will be displayed to the user when they select slots.

Response parameters #

real_time_scheduling.real_time_scheduling_id  #

The Cronofy unique identifier for the Real Time Scheduling link.

real_time_scheduling.url  #

The URL to direct the user to in order to authorize their calendar account and have the event inserted into their selected calendar.

Example callback #

Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "start": {
      "time": "2022-01-20T10:00:00Z",
      "tzid": "Europe/London"
    "end": {
      "time": "2022-01-20T11:00:00Z",
      "tzid": "Europe/London"
    "summary": "Product Manager Interview at Globex"
  "participants": [
    { "sub": "acc_567236000909002" }
  "user": {
    "tzid": "Europe/Paris"

Callback request headers #

Cronofy-HMAC-SHA256  #

Can optionally be used to verify that the notification was sent by Cronofy

This HMAC uses the SHA256 algorithm, keyed with the application's client secret, to generate a Base64 encoded hash of the request body.

When an application has multiple active client secrets, a value is generated for each active secret, separated by commas. For example:


Examples are available in our cronofy/notification-hmac-examples Github repository, and our API libraries include methods to verify this header.

Callback request parameters #

event  #

An object with the details of the event created by an available time slot being selected. Details of what parameters this object can hold can be found in the create or update event documentation.

participants  #

An array of all the participants which were selected for the event based on their availability.

user.tzid  #

An optional parameter that indicates the timezone the user selected before choosing the time slot. If not present then the scheduling flow was rendered in the timezone defined for the event.

Localization #

The scheduling page displayed when a user navigates to the Real Time Scheduling URL will detect the user’s browser locale and render accordingly.

Currently supported locales are:

  • cs Czech
  • cy Welsh
  • de German
  • en US English (default)
  • fr French
  • fr-CA Canadian French
  • it Italian
  • ja Japanese
  • nl Dutch
  • pt-BR Brazilian Portuguese
  • ru Russian
  • sv Swedish

Use of one of the supported locales can be forced by adding a locale query string parameter to the Real Time Scheduling URL, for example:

In This Section