Alpha API Documentation

If you have any questions that aren't covered here or need any help with using the API, don't hesitate to email us or post a question to our API Mailing List.


Introduction

These are new additions to the Cronofy API that haven't been used in anger.

We are confident that they work, but are aware they haven't been hardened by real world usage.

Whilst we do not expect to make any breaking changes once an addition to the API reaches this point this may happen at some point in the future. Therefore, if you are using an alpha feature of the API, please let us know and we can keep you informed of any such changes.

Can't find the feature you're looking for?

The feature has probably been moved into our main API docs

Otherwise contact support@cronofy.com for help.


Authorization - Explicit Linking

Description

By default, Cronofy implicitly links calendar accounts that authorize using the same browser. The mechanism used is a persistent cookie.

This feature allows the calling application request that the calendar account authorized to be explicitly linked to a pre-existing Cronofy account. This enables combining authorizations across different devices.

The mechanism used is the generation of a temporary link_token which is passed to the authorization page to identify the account to be linked to.

This is an experimental feature and is enabled on a per application basis. Contact support@cronofy.com if you would like access to this.

Generating a Link Token

Using the access_token for the pre-existing account you wish to link, POST to the /v1/link_tokens end point.

The response will contain the link_token.

Example Request

POST /v1/link_tokens HTTP/1.1
HOST: api.cronofy.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 200 OK
{
    "link_token" : "{LINK_TOKEN}"
}

Requesting a Linked Authorization

The link_token is then passed as an additional query string parameter to the authorization request URL, eg:

https://app.cronofy.com/oauth/authorize
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &scope={SCOPE}
    &state={STATE}
    &link_token={LINK_TOKEN}

See https://www.cronofy.com/developers/api/#request-authorization


Batch

Description

The batch endpoint effectively allows up to 50 requests to be sent at once.

The following requests are supported by the batch endpoint:

URL format

api.cronofy.com/v1/batch

Example Request

POST /v1/batch HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "batch": [
    {
      "method": "DELETE",
      "relative_url": "/v1/calendars/cal_123_abc/events",
      "data": {
        "event_id": "456"
      }
    },
    {
      "method": "POST",
      "relative_url": "/v1/calendars/cal_123_abc/events",
      "data": {
        "event_id": "qTtZdczOccgaPncGJaCiLg",
        "description": "Discuss plans for the next quarter.",
        "start": "2014-08-05T15:30:00Z",
        "end": "2014-08-05T17:00:00Z",
        "location": {
          "description": "Board room"
        }
      }
    }
  ]
}

Example Response

HTTP/1.1 207 Multi-Status
Content-Type: application/json; charset=utf-8

{
  "batch": [
    { "status": 202 },
    {
      "status": 422,
      "data": {
        "errors": {
          "summary": [
            { "key": "errors.required", "description": "summary must be specified" }
          ]
        }
      }
    }
  ]
}

Request parameters

batch required

An array of up to 50 requests that form part of the batch.

batch.method required

A String for the HTTP method of the individual request. Maps directly from its main documentation.

batch.relative_url required

A String for the relative URL (sometimes referred to as the path and query string) of the individual request. Maps directly from its main documentation.

batch.data required

An object containing the body parameters of the request. Maps directly from its main documentation.

Note that this is an object, not a JSON-encoded string.

Response parameters

batch required

An array of responses corresponding directly to each request.

batch.status required

An Integer for the HTTP response code to the individual request.

Note that a 404 Not Found response code may also indicate that the request is not supported by the batch endpoint.

batch.headers optional

An object containing the headers of the individual response.

batch.data optional

An object containing the body of the individual response.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement auth_token before the request is retried.


Read Available Periods

Description

Returns a list of available periods for the authorized account.

The returned available periods will start before the given to Date and will end on or after the given from Date.

Example Request

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request's path for clarity.

GET /v1/available_periods?from={FROM_DATE}&to={TO_DATE}
    &tzid={TZID} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

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

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/available_periods/pages/08a07b034306679e"
  },
  "available_periods": [
    {
      "available_period_id": "qTtZdczOccgaPncGJaCiLg",
      "start": "2018-11-26T15:30:00Z",
      "end": "2018-11-26T17:00:00Z"
    }
  ]
}

Request parameters

from optional

The minimum Date from which to return available periods.

to optional

The Date to return available periods up until.

Note that the results will not include available periods occurring on this date.

tzid optional

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

It is recommended that you use the same tzid for all requests made for an individual user in order to ensure all their available periods are returned to you.

Required if specifying either from or to

localized_times optional

A Boolean specifying whether the available periods should have their start and end times returned with any available localization information.

If not provided the start and end times will be returned as simple Time values.

Response parameters

pages.current

An Integer specifying which page of the result set the current request is for.

pages.total

An Integer specifying the total number of pages in the result set.

pages.next_page optional

When present, a String specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a GET request to this URL and you will receive a response in the same format as a regular read events request.

available_periods.available_period_id

The available_period_id you specified when creating the available period.

available_periods.start

When localized_times is not specified or is false, the Time or Date representing when the available period starts.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the available period starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
available_periods.end

When localized_times is not specified or is false, the Time or Date by which the available period ends.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the available period ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

Create or Update Available Period

Description

Creates or updates an available period for the authenticated account.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

It can also be used in conjunction with the Batch endpoint to update multiple periods at once.

URL format

api.cronofy.com/v1/available_periods

Example Request

POST /v1/available_periods HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "available_period_id": "qTtZdczOccgaPncGJaCiLg",
  "start": "2018-11-26T15:30:00Z",
  "end": "2018-11-26T17:00:00Z"
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

available_period_id required

The String that uniquely identifies the available period. The first request made for an available_period_id will create an available period for the account and subsequent requests will update its details.

Usually this will be your own internal ID for the available period, encoded as an ASCII-only String of up to 64 characters.

start required

The start time can be provided as a simple Time string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time to use as the start of the available period. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the start time of the available period.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

end required

The end time can be provided as a simple Time string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time to use as the end time of the event. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous. Also, it must be later in time than the start of the event.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the end time of the event.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

tzid optional

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the default tzid to use for the start and end times of the available period if they do not specify their own.

If not provided, Etc/UTC is used by default.


Delete Available Period

Description

Deletes an available period for the authenticated account.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

It can also be used in conjunction with the Batch endpoint to delete multiple periods at once.

URL format

api.cronofy.com/v1/available_periods

Example Request

DELETE /v1/available_periods HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "available_period_id": "qTtZdczOccgaPncGJaCiLg"
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

available_period_id required

The String that uniquely identifies the available period.

Usually this will be your own internal ID for the available period, encoded as an ASCII-only String of up to 64 characters.


Bulk Delete Available Periods

Description

Deletes all available periods for the authenticated account.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

It can also be used in conjunction with the Batch endpoint.

URL format

api.cronofy.com/v1/available_periods

Example Request

DELETE /v1/available_periods HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{

  "delete_all": true
}

Example Response

HTTP/1.1 202 Accepted

Request parameters

delete_all required

A Boolean specifying whether all available period you are managing for the authenticated account should be deleted. When specified must be true.


Read Availability Rule

Description

Retrieves an availability rule.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

URL format

api.cronofy.com/v1/availability_rules/{availability_rule_id}

Example Request

GET /v1/availability_rules/{availability_rule_id} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Request parameters

availability_rule_id required

The String that uniquely identifies the availability rule. The first request made for an availability_rule_id will create an available period for the account and subsequent requests will update its details.

Usually this will be your own internal ID for the available period, encoded as an ASCII-only String of up to 64 characters.

Example Response

HTTP/1.1 200 Success

{
  "availability_rule_id": "default",
  "tzid": "America/Chicago",
  "calendar_ids": [
    "cal_n23kjnwrw2_jsdfjksn234"
  ],
  "weekly_periods": [
    {
      "day": "monday",
      "start_time": "09:30",
      "end_time": "12:30"
    },
    {
      "day": "wednesday",
      "start_time": "09:30",
      "end_time": "12:30"
    }
  ]
}

Response parameters

availability_rule_id

The String that uniquely identifies the availability rule. The first request made for an availability_rule_id will create an available period for the account and subsequent requests will update its details.

Usually this will be your own internal ID for the available period, encoded as an ASCII-only String of up to 64 characters.

tzid required

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
calendar_ids

An Array specifying the calendars that should impact the user's availability. When provided at least one calendar must be specified.

weekly_periods

An Array of weekly recurring periods for the availability rule.

weekly_period.day

A String the week day this period applies to.

Valid options are:

  • sunday
  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
weekly_period.start_time

A String the time of day the period should start expressed as a 24hr clock string, eg: 09:30.

weekly_period.end_time

A String the time of day the period should end expressed as a 24hr clock string, eg: 16:30.


Create or Update Availability Rule

Description

Creates or updates an availability rule for the authenticated account.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

URL format

api.cronofy.com/v1/availability_rules

Example Request

POST /v1/availability_rules HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "availability_rule_id": "default",
  "tzid": "America/Chicago",
  "calendar_ids": [
    "cal_n23kjnwrw2_jsdfjksn234"
  ],
  "weekly_periods": [
    {
      "day": "monday",
      "start_time": "09:30",
      "end_time": "12:30"
    },
    {
      "day": "wednesday",
      "start_time": "09:30",
      "end_time": "12:30"
    }
  ]
}

Request parameters

availability_rule_id required

The String that uniquely identifies the availability rule. The first request made for an availability_rule_id will create an available period for the account and subsequent requests will update its details.

Usually this will be your own internal ID for the available period, encoded as an ASCII-only String of up to 64 characters.

tzid required

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
calendar_ids optional

An Array specifying the calendars that should impact the user's availability. When provided at least one calendar must be specified.

weekly_periods required

An Array of weekly recurring periods for the availability rule.

weekly_period.day required

A String the week day this period applies to.

Valid options are:

  • sunday
  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday
weekly_period.start_time required

A String the time of day the period should start expressed as a 24hr clock string, eg: 09:30.

weekly_period.end_time required

A String the time of day the period should end expressed as a 24hr clock string, eg: 16:30.

Example Response

HTTP/1.1 200 Success

{
  "availability_rule_id": "default",
  "tzid": "America/Chicago",
  "calendar_ids": [
    "cal_n23kjnwrw2_jsdfjksn234"
  ],
  "weekly_periods": [
    {
      "day": "monday",
      "start_time": "09:30",
      "end_time": "12:30"
    },
    {
      "day": "wednesday",
      "start_time": "09:30",
      "end_time": "12:30"
    }
  ]
}

Delete Available Period

Description

Deletes an availability rule for the authenticated account.

This can be used in combination with our Real-Time Scheduling and Availability features to manage an account's availability dynamically.

URL format

api.cronofy.com/v1/availability_rules/{availability_rule_id}

Example Request

DELETE /v1/availability_rules/{availability_rule_id} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response

HTTP/1.1 202 Accepted

Request parameters

availability_rule_id required

The String that uniquely identifies the availability rule.

Usually this will be your own internal ID for the availability rule, encoded as an ASCII-only String of up to 64 characters.


Managed Availability

Description

When managing an account's availability through Available Periods you can then use those to impact on their availability when using the Availability and Real-Time Scheduling endpoints.

Rather than the available periods being fixed as part of those requests, when you signal that managed availability should be used for a member, their managed availability is referenced dynamically.

Example Availability Request

POST /v1/availability HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002",
          "managed_availability": true
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2018-11-26T00:00:00Z",
      "end": "2018-12-03T23:59:59Z"
    }
  ]
}

Request parameters

participants.members.managed_availability optional

A Boolean specifying whether managed availability should be taken into account for this member.

If not provided, defaults to false.


Availability Buffers

Description

As part of an Availability query, buffer times can be specified to ensure that there is a gap between a busy period and an available period.

Example Availability Request

POST /v1/availability HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002",
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2018-11-26T00:00:00Z",
      "end": "2018-12-03T23:59:59Z"
    }
  ],
  "buffer": {
    "before": { "minutes": 30 },
    "after": { "minutes": 15 }
  }
}

Request parameters

buffer.before.minutes optional

An Integer specifying the minimum number of minutes that must be free before the available period starts.

Must be a positive value.

buffer.after.minutes optional

An Integer specifying the minimum number of minutes that must be free after the available period ends.

Must be a positive value.


Real Time Scheduling - Buffers

Description

As part of an Real Time Scheduling request, buffer times can be specified to ensure that there is a gap between a busy period and a selectable slot.

Example Request

POST /v1/real_time_scheduling HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "oauth": {
    "redirect_uri": "{REDIRECT_URI}",
    "scope": "create_event",
    "state": "{STATE}"
  },
  "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"
      }
    ],
    "buffer": {
      "before": { "minutes": 30 },
      "after": { "minutes": 15 }
    },
    "required_duration": { "minutes": 60 },
    "available_periods": [
      { "start": "2018-11-26T09:00:00Z", "end": "2018-11-26T18:00:00Z" }
    ]
  },
  "target_calendars": [
    {
      "sub": "acc_567236000909002",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234"
    }
  ],
  "callback_url": "http://www.example.com/callback"
}

Request parameters

availability.buffer.before.minutes optional

An Integer specifying the minimum number of minutes that must be free before the available period starts.

Must be a positive value.

availability.buffer.after.minutes optional

An Integer specifying the minimum number of minutes that must be free after the available period ends.

Must be a positive value.


Buffer Examples

Buffers allow availablity and Real Time Scheduling requests to define a minimum gap before or after a busy period without an event being created. This reduces the available period by the buffer size in order to create the gap.

For example using a before buffer of 30 minutes.

{
    "before": {
        "minutes": 30
    }
}

Will result in a period being available for a new event with a buffered time blocked out before the new event can occur.

10 Busy Period  
 
11  
  Before buffer
12   New Event
 

In addition to before buffers we also support the concept of after buffers. These work in a similar way to before buffers but are evalulated after the new event should occur.

For example using an after buffer of 30 minutes.

{
    "after": {
        "minutes": 30
    }
}

Will result in a period being available for a new event with a buffered time blocked out after the new event occurs.

9   New Event
 
10   After buffer
Busy Period  
11  
 

We also support being able to specify both an before and after buffer, these can be the same value or different depending on the requirements.

For example specifying both before and after buffers to 30 minutes.

{
    "before": {
        "minutes": 30
    },
    "after": {
        "minutes": 30
    }
}
9   New Event
 
10   After buffer
Busy Period  
11  
  Before buffer
12   New Event
 

Real Time Scheduling - Start Interval

Description

As part of an Real Time Scheduling request, a start interval can be specified to constrain when the available periods can begin, for example every 15 minutes or every 30 minutes.

Example Request

POST /v1/real_time_scheduling HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "oauth": {
    "redirect_uri": "{REDIRECT_URI}",
    "scope": "create_event",
    "state": "{STATE}"
  },
  "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 },
    "start_interval": { "minutes": 60 },
    "available_periods": [
      { "start": "2018-11-26T09:00:00Z", "end": "2018-11-26T18:00:00Z" }
    ]
  },
  "target_calendars": [
    {
      "sub": "acc_567236000909002",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234"
    }
  ],
  "callback_url": "http://www.example.com/callback"
}

Request parameters

availability.start_interval.minutes optional

An Integer describing the frequency that an available period can start on.

For example, for 30 available periods will start every 30 minutes.

Must be one of 5, 10, 15, 30, 60.

If omitted the entire period will be returned.

Start Interval Examples

By default Real Time Scheduling will use the required duration to derive the interval of slots. For example an 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

Real Time Scheduling - Completed Redirect URL

Description

As part of an Real Time Scheduling request, a URL can be provided that user will be redirected to when they have chosen a time slot.

They will also be redirected to this URL if they revisit the real time scheduling page after they've completed the process.

Example Request

POST /v1/real_time_scheduling HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "oauth": {
    "redirect_uri": "{REDIRECT_URI}",
    "scope": "create_event",
    "state": "{STATE}"
  },
  "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 },
    "start_interval": { "minutes": 60 },
    "available_periods": [
      { "start": "2018-11-26T09:00:00Z", "end": "2018-11-26T18:00:00Z" }
    ]
  },
  "target_calendars": [
    {
      "sub": "acc_567236000909002",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234"
    }
  ],
  "callback_url": "http://www.example.com/callback",
  "redirect_urls": {
    "completed_url": "http://www.example.com/success"
  }
}

Request parameters

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.


Real Time Scheduling Status

Description

Retrieves the current state of a Real Time Scheduling link.

URL format

api.cronofy.com/v1/real_time_scheduling?token={token}

Example Request

POST /v1/real_time_scheduling?token={token} HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Request parameters

token required

The String that is returned on the completed_url redirect query string.

Example Response

HTTP/1.1 200 Success

{
  "real_time_scheduling": {
    "real_time_scheduling_id": "sch_4353945880944395",
    "url": "{REAL_TIME_SCHEDULING_URL}",
    "event": {...},
    "status": "completed"
  }
}

Response parameters

real_time_scheduling.real_time_scheduling_id

The Cronofy identifier for the Real Time Scheduling link, a String.

real_time_scheduling.url

The URL to direct the user to in order for them to select a time slot.

real_time_scheduling.event

The current state of the event associated with the link. Once completed the event will have start and end values.

real_time_scheduling.status

The String describing the current status of the link. Possible values:

  • open a slot hasn't been chosen.
  • completed a slot has been chosen.

Sequencing

Introduction

Sequences are a means of defining a series of events which should be scheduled. The Sequenced Availability API allows an application to find availability for each step in this sequence.

A typical workflow of Sequenced Availability would be:

  1. User defines sequence of events to schedule with desired attendees.
  2. Application checks Availability for sequence for desired events each with a unique sequence_id.
  3. Application renders options to user to select from.
  4. User makes selection of sequence.
  5. Application upserts events in attendees calendars using selected option and sequence_id as a lookup for each event.

Sequenced Availability

Description

Inspects calendars to determine the common availablity for a number of pre-defined events. For example scheduling a series of events for an interview process.

URL format

api.cronofy.com/v1/sequenced_availability

Example Request

POST /v1/sequenced_availability HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "sequence":[
    {
      "sequence_id":"123",
      "ordinal":1,
      "participants":[
        {
          "members":[
            {
              "sub":"acc_567236000909002",
              "calendar_ids":[ "cal_n23kjnwrw2_jsdfjksn234" ]
            }
          ],
          "required":"all"
        }
      ],
      "required_duration":{ "minutes": 60 },
      "start_interval":{ "minutes": 60 },
      "buffer":{
        "before":{
          "minimum": { "minutes" : 30 },
          "maximum": { "minutes" : 60 }
        },
        "after":{
          "minimum": { "minutes" : 15 },
          "maximum": { "minutes" : 30 }
        }
      }
    },
    {
      "sequence_id":"456",
      "ordinal":2,
      "participants":[
        {
          "members":[
            {
              "sub":"acc_678347111010113",
              "available_periods": [
                {
                  "start": "2018-11-26T09:00:00Z",
                  "end": "2018-11-26T12:00:00Z"
                },
                {
                  "start": "2018-11-27T10:00:00Z",
                  "end": "2018-11-27T20:00:00Z"
                }
              ]
            }
          ],
          "required":"all"
        }
      ],
      "required_duration":{ "minutes": 60 },
      "start_interval":{ "minutes": 60 },
      "buffer":{
        "before":{
          "minimum": { "minutes" : 30 },
          "maximum": { "minutes" : 60 }
        },
        "after":{
          "minimum": { "minutes" : 15 },
          "maximum": { "minutes" : 30 }
        }
      }
    }
  ],
  "available_periods": [
    {
      "start": "2018-11-26T09:00:00Z",
      "end": "2018-11-26T18:00:00Z"
    },
    {
      "start": "2018-11-27T09:00:00Z",
      "end": "2018-11-27T18:00:00Z"
    }
  ]
}

Example Response

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

{
  "sequences":[
    {
      "sequence":[
        {
          "sequence_id":"123",
          "start": "2018-11-26T09:00:00Z",
          "end": "2018-11-26T10:00:00Z",
          "participants":[ { "sub":"acc_567236000909002" } ]
        },
        {
          "sequence_id":"456",
          "start": "2018-11-26T10:00:00Z",
          "end": "2018-11-26T11:00:00Z",
          "participants":[ { "sub":"acc_678347111010113" } ]
        }
      ]
    },
    {
      "sequence":[
        {
          "sequence_id":"123",
          "start": "2018-11-26T11:00:00Z",
          "end": "2018-11-26T12:00:00Z",
          "participants":[ { "sub":"acc_567236000909002" } ]
        },
        {
          "sequence_id":"456",
          "start": "2018-11-26T12:00:00Z",
          "end": "2018-11-26T13:00:00Z",
          "participants":[ { "sub":"acc_678347111010113" } ]
        }
      ]
    }
  ]
}

Request parameters

sequence required

An array containing the parts of the sequence to find availability for.

A maximum of 5 parts can be specified for a sequence

sequence.sequence_id required

A String value to identify this part of the sequence, must be unique for this request.

sequence.ordinal optional

A Integer value to define the order of this part of the sequence, this is used to determine desired order of the sequence.

sequence.participants required

An array of the groups of participants whose availability should be taken into account.

At least one group must be specified, a maximum of 10 accounts may be specified over a combination of groups.

sequence.participants.members required

An array of participants that should have their availability taken into account as part of this group.

At least one participant must be specified and you must have been granted the read_free_busy scope for each participant involved in the availability request.

Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free-busy so you do not have to have both.

sequence.participants.members.sub required

The internal Cronofy ID for the account, as an ASCII-only String.

This can be retrieved by calling the UserInfo endpoint with a valid access_token

sequence.participants.members.available_periods optional

An array of 1 to 10 available periods within which the member is available. If omitted it is assumed the member is available whenever they do not have a "busy" event in their calendar.

sequence.participants.members.available_periods.start required

Thestart of an available period as a Time.

It must represent a future point in time.

sequence.participants.members.available_periods.end required

Theend of an available period as a Time.

Must be between 1 minute and 35 days after the correspondingstart.

sequence.participants.members.calendar_ids optional

Restricts the events contributing towards the members availability to those within the set of specified calendar_ids.

sequence.participants.required required

Either a String of all to specify that all members of the group need to be available for a period to be viable, or an Integer of 1 to specify that at least one member of the group must be available.

sequence.required_duration required

An object describing the minimum period that the participant groups must be satisfied for a period to be deemed as available.

sequence.required_duration.minutes required

An Integer specifying the number of minutes that an available period must last to be considered viable.

Must be a value of at least 1.

sequence.available_periods required

An array of 1 to 10 available periods, across up to 35 days of the period of synchronized events, within which suitable matches may be found.

sequence.available_periods.start required

Thestart of an available period as a Time.

It must represent a future point in time.

sequence.available_periods.end required

Theend of an available period as a Time.

Must be between 1 minute and 35 days after the correspondingstart.

sequence.buffer.before.minimum.minutes optional

An Integer specifying the minimum number of minutes that must be free before the event starts.

Must be a positive value.

sequence.buffer.before.maximum.minutes optional

An Integer specifying the maximum number of minutes that must be free before the event starts.

Must be a positive value.

sequence.buffer.after.minimum..minutes optional

An Integer specifying the minimum number of minutes that must be free after the event ends.

Must be a positive value.

sequence.buffer.before.maximum.minutes optional

An Integer specifying the maximum number of minutes that must be free before the event ends.

Must be a positive value.

sequence.start_interval optional

An object describing the frequency that a sequence can start on.

For example, "every 30 minutes" or "every 15 minutes".

sequence.start_interval.minutes required

An Integer specifying the frequency of the event start.

Must be one of 5, 10, 15, 30, 60.

Response parameters

sequences

An array of possible sequences that match the criteria specified in the request.

sequences.sequence

An array of available periods which meet the criteria specifed in the request.

sequences.sequence.sequence_id

A value to identify this part of the sequence.

sequences.sequence.start

Thestart of an available period as a Time.

sequences.sequence.end

Theend of an available period as a Time.

sequences.sequence.participants

An array of participants that are available for the given period.

sequences.sequence.participants.sub

The internal Cronofy ID for the account, as an ASCII-only String.

Error responses

401 Unauthorized

The request was refused as the provided authentication credentials were not recognized.

Note that whilst many accounts can be part of the availability request that authentication is performed via theaccess_token for only one of them.

When an OAuthrefresh_token is available then it should be used to request a replacementauth_token before the request is retried.

402 Payment Required

The request was refused as your plan does not include the required feature.

422 Unprocessable

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required required_duration parameter, you would receive a response like:

{
  "errors": {
    "required_duration": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.


Real-Time Sequencing

Description

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

URL format

api.cronofy.com/v1/real_time_scheduling

Example Request

POST /v1/real_time_sequencing HTTP/1.1
Host: api.cronofy.com
Content-Type: application/json; charset=utf-8

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "oauth": {
    "redirect_uri": "{REDIRECT_URI}",
    "scope": "create_event",
    "state": "{STATE}"
  },
  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "summary": "Product Manager Interview at Globex",
    "tzid": "Europe/London"
  },
  "availability": {
      "sequence":[
        {
          "sequence_id":"123",
          "ordinal":1,
          "participants":[
            {
              "members":[
                {
                  "sub":"acc_567236000909002",
                  "calendar_ids":[ "cal_n23kjnwrw2_jsdfjksn234" ]
                }
              ],
              "required":"all"
            }
          ],
          "event": {
            "event_id": "qTtZdczOccgaPncGJaCiLg",
            "summary": "Pre screen"
          },
          "required_duration":{ "minutes": 60 }
        },
        {
          "sequence_id":"456",
          "ordinal":2,
          "participants":[
            {
              "members":[
                {
                  "sub":"acc_678347111010113",
                  "available_periods": [
                    {
                      "start": "2018-11-26T09:00:00Z",
                      "end": "2018-11-26T12:00:00Z"
                    },
                    {
                      "start": "2018-11-27T10:00:00Z",
                      "end": "2018-11-27T20:00:00Z"
                    }
                  ]
                }
              ],
              "required":"all"
            }
          ],
          "event": {
            "event_id": "qTtZdczOccgaPncGJaCiLg",
            "summary": "Face to facd"
          },
          "required_duration":{ "minutes": 60 }
        }
      ],
      "available_periods": [
        {
          "start": "2018-11-26T09:00:00Z",
          "end": "2018-11-26T18:00:00Z"
        },
        {
          "start": "2018-11-27T09:00:00Z",
          "end": "2018-11-27T18:00:00Z"
        }
      ]
  },
  "target_calendars": [
    {
      "sub": "acc_567236000909002",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234"
    }
  ],
  "callback_url": "http://www.example.com/callback"
}

Example Response

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

{
  "url": "{REAL_TIME_SCHEDULING_URL}"
}

Request parameters

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.

Please note that event.attendees is not supported for Real Time Scheduling.

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 sequence date and time. Details of what parameters this object can hold can be found in the Availability documentation.

availability.sequence.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.

Please note that event.attendees is not supported for Real Time Scheduling.

The start and end parameters should be omited.

Response parameters

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

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

{
  "event": {
    "event_id": "qTtZdczOccgaPncGJaCiLg",
    "start": {
      "time": "2018-11-26T11:00:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2018-11-26T13:00:00Z",
      "tzid": "Europe/London"
    },
    "summary": "Product Manager Interview at Globex"
  },
  "participants": [
    { "sub": "acc_567236000909002" }
  ],
  "sequence":[
    {
      "sequence_id":"123",
      "event": {
        "event_id": "qTtZdczOccgaPncGJaCiLg",
        "start": "2018-11-26T11:00:00Z",
        "end": "2018-11-26T12:00:00Z",
        "summary": "Pre screen"
      },
      "participants":[ { "sub":"acc_567236000909002" } ]
    },
    {
      "sequence_id":"456",
      "event": {
        "event_id": "qTtZdczOccgaPncGJaCiLg",
        "start": "2018-11-26T12:00:00Z",
        "end": "2018-11-26T13:00:00Z",
        "summary": "Face to face"
      },
      "participants":[ { "sub":"acc_678347111010113" } ]
    }
  ]
} 

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 base-64 encoded hash of the request body.

Examples are available in our cronofy/notification-hmac-examples Github repository.

Request parameters

event

An object with the details of the end users event based on the period of time 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 events contained in the sequence based on their availability.

sequence

An array of available periods which match the selection made by the user in Real Time Scheduling.

sequence.sequence_id

A value to identify this part of the sequence.

sequence.start

Thestart of an available period as a Time.

sequence.end

Theend of an available period as a Time.

sequence.participants

An array of participants that are available for the given period.

sequence.participants.sub

The internal Cronofy ID for the account, as an ASCII-only String.


Sequencing Examples

Scheduling a simple set of events is simply a case of making a sequence with the steps defined in the desired order.

For example scheduling 3 sequential events of 30 minutes each for a given account:

[
    {
      "sequence_id":"First Event",
      "ordinal":1,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 }
    },
    {
      "sequence_id":"Second Event",
      "ordinal":2,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 }
    }
]

The scheduling engine will determine a number of possible times this sequence of events can occur in.

For example it may be possible to schedule the events with each starting as the previous has finished.

9   First Event
  Second Event
10 Busy Period  
 

Or it may be required that we schedule around an existing event in order to fit the events into the available period.

9    
  First Event
10 Busy Period  
 
11   Second Event
   

Buffers

In addition to creating a sequence we can also define a buffer time between each step of the sequence, for example before and after each step 30 minutes.

A request creating 2 events with buffer formed like so:

[
    {
      "sequence_id":"First Event",
      "ordinal":1,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 },
      "buffer":{
        "before": { "minutes" : 30 },
        "after": { "minutes" : 30 }
      }
    },
    {
      "sequence_id":"Second Event",
      "ordinal":2,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 },
      "buffer":{
        "before": { "minutes" : 30 },
        "after": { "minutes" : 30 }
      }
    }
]

Its important to note that although both the first and second steps have before and after buffers these are collaped into one when the events are sequential.

9 Before buffer  
First Event  
10 After buffer Before buffer
  Second Event
11   After buffer
   

However if the events are separated by a busy period both buffers will still be honoured.

9   Before buffer
  First Event
10   After buffer
Busy Period  
11   Before buffer
  Second Event
12   After buffer
   

Maximum buffer

We can also define buffers which have a maximum value associated with them, this is useful when generating a sequence to constain the total time a sequence can occupy.

For example defining a buffer with a minimum of 30 minutes and a maximum of 60 will allow a buffer of between 30 and 60 minutes between each sequence step

We can change our previous example to add in this constaint:

[
    {
      "sequence_id": "First Event",
      "ordinal": 1,
      "participants": [{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration": { "minutes": 30 },
      "buffer": {
        "after": {
          "maximum": { "minutes" : 60 }
        }
      }
    },
    {
      "sequence_id": "Second Event",
      "ordinal": 2,
      "participants": [{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration": { "minutes": 30 }
    }
]

This request means it is possible to generate a sequence with a 30 minute busy period in between as this is within the maximum buffer.

9 First Event
Busy Period
10 Second Event
 

However if the busy period is longer than 30 minutes we will exceed the maximum buffer so the following example is not valid as the maximum buffer will be exceeded.

9 First Event
Busy Period
10
11 Second Event
 

Start Intervals

Start intervals can also be used in a sequencing request, these are applied at each step to define when the step can start.

For example if two 30 minute steps have a 60 minute start interval this will create a minimum of a 30 minute gap between the events

[
    {
      "sequence_id": "First Event",
      "ordinal": 1,
      "participants": [{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration": { "minutes": 30 },
      "start_interval": { "minutes": 60 }
    },
    {
      "sequence_id": "Second Event",
      "ordinal": 2,
      "participants": [{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration": { "minutes": 30 },
      "start_interval": { "minutes": 60 }
    }
]

Without a specifed start interval specified the sequence could be scheduled every 30 minutes.

9 First Event
Second Event
10  
 

However adding a start interval of 60 minutes would mean a 30 minute gap is created between the steps.

9 First Event
 
10 Second Event
 

Ordering

In the previous example we specified an order for events by setting the ordinial value for each step, this value is optional and if omitted the ordinal is derived from position in the the array.

We also support the ability to specify a non-determined ordering of a sequence by which we mean the events can occur in any order. We also allow this to be defined partially along with ordered events to define a soft ordering.

For example an interview sequence where we must have an introduction first but the Face to Face and Coding Exercise can occur in any order.

[
    {
      "sequence_id":"Introduction",
      "ordinal":1,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 }
    },
    {
      "sequence_id":"Face to Face",
      "ordinal":2,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 }
    },
    {
      "sequence_id":"Coding Exercise",
      "ordinal":2,
      "participants":[{
          "members":[{ "sub":"acc_567236000909002" }],
          "required":"all"
      }],
      "required_duration":{ "minutes": 30 }
    }
]

There are two possible orders this sequence can be generated in, the sequencing engine will consider each option to determine the best possible selection.

9 Introduction
Face to Face
10 Coding Execise
 
9 Introduction
Coding Execise
10 Face to Face
 

Smart Invites - Multiple Recipients

Allows the creation of Smart Invites with multiple recipients.

As the behavior is very similar to the single recipient functionality it is recommended that you familiarize yourself with the exisiting Smart Invites documentation first.

The key difference is that rather than having a single recipient element or recipient_email parameter, there is instead a recipients collection.


Create or Update Invite

Description

Create a new Smart Invite for multiple recipients.

URL format

api.cronofy.com/v1/smart_invites

Example Request

POST /v1/smart_invites HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "method": "request",
  "recipients": [
    { "email": "cronofy@example.com" },
    { "email": "cronofy@example.org" }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2017-10-05T09:30:00Z",
    "end": "2017-10-05T10:00:00Z",
    "tzid": "Europe/London",
    "location": {
      "description": "Board room"
    }
  },
  "organizer": {
    "name": "Smart invite application"
  }
}

Example Response

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

{
  "recipients": [
    {
      "email": "cronofy@example.com",
      "status": "pending"
    },
    {
      "email": "cronofy@example.org",
      "status": "pending"
    }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": {
      "time": "2017-10-05T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2017-10-05T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}

Example callback

Once a Smart Invite has been created for multiple recipients you will be able to receive notifications relating to it. These notifications will be sent as HTTP POST requests to the callback_url specified when the Smart Invite was created.

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

{
  "notification": {
    "type": "smart_invite",
  },
  "smart_invite": {
    "smart_invite_id": "example_id",
    "callback_url": "http://www.example.com",
    "recipients": [
      {
        "email": "example@example.com",
        "status": "tentative",
        "comment": "example comment",
        "proposal": {
          "start": {
            "time": "2014-09-13T23:00:00+02:00",
            "tzid": "Europe/Paris"
          },
          "end": {
            "time": "2014-09-13T23:00:00+02:00",
            "tzid": "Europe/Paris"
          }
        }
      },
      {
        "email": "cronofy@example.org",
        "status": "pending"
      }
    ],
    "reply": {
      "email": "example@example.com",
      "status": "tentative",
      "comment": "example comment",
      "proposal": {
        "start": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    }
  }
}

The key difference is that rather than having a single recipient element in the response, there is instead a recipients collection. The reply still relates to the specific response that triggered the notification.


Invite Status

Description

Retrieve the current state of a Smart Invite created for multiple recipients.

Example Request

GET /v1/smart_invites?smart_invite_id=your-unique-id-for-invite
HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {API_KEY}

Example Response

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

{
  "recipients": [
    {
      "email": "example@example.com",
      "status": "tentative",
      "comment": "example comment",
      "proposal": {
        "start": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    },
    {
      "email": "cronofy@example.org",
      "status": "pending"
    }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": {
      "time": "2017-10-05T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2017-10-05T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  }
}

The difference to the request is that no recipient_email should be provided.

For the response, the difference is that rather than having a single recipient element and a replies collection in the response, there is instead a recipients collection.


Cancel Invite

Description

This method allows an invite to be cancelled, please note the returned ICS attachment must be sent to the recipients in order for the event to be removed from their calendar.

URL format

api.cronofy.com/v1/smart_invites

Example Request

POST /v1/smart_invites HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "method": "cancel",
  "recipients": [
    { "email": "cronofy@example.com" },
    { "email": "cronofy@example.org" }
  ],
  "smart_invite_id": "your-unique-id-for-invite"
}

Example Response

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

{
  "recipients": [
    {
      "email": "example@example.com",
      "status": "tentative",
      "comment": "example comment",
      "proposal": {
        "start": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2014-09-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    },
    {
      "email": "cronofy@example.org",
      "status": "pending"
    }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": {
      "time": "2017-10-05T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2017-10-05T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}

Smart Invites - Initial Status

Allows the creation of Smart Invites with recipients given an initial status other than pending.

URL format

api.cronofy.com/v1/smart_invites

Example Request

POST /v1/smart_invites HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "method": "request",
  "recipients": [
    {
      "email": "cronofy@example.com",
      "status": "accepted"
    },
    { "email": "cronofy@example.org" }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2017-10-05T09:30:00Z",
    "end": "2017-10-05T10:00:00Z",
    "tzid": "Europe/London",
    "location": {
      "description": "Board room"
    }
  },
  "organizer": {
    "name": "Smart invite application"
  }
}

Example Response

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

{
  "recipients": [
    {
      "email": "cronofy@example.com",
      "status": "accepted"
    },
    {
      "email": "cronofy@example.org",
      "status": "pending"
    }
  ],
  "smart_invite_id": "your-unique-id-for-invite",
  "callback_url": "https://example.yourapp.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": {
      "time": "2017-10-05T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2017-10-05T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}

Request parameters

recipients.status optional

The initial status for the recipient as a String, can be one of:

  • accepted
  • declined
  • pending (default)
  • tentative