Required plan: Scheduler

Description #

Creates a Scheduler Request using a Cronofy Account.

Authentication is with a client_secret of an Internal Application linked to the Organizational Unit.

Also supports the sub of an Account connected to the Organizational Unit in the Cronofy-Impersonate header.

The host for the resulting meeting is decided in one of two ways.

  1. Specify host in the payload.
  "host": {
    "sub": "acc_5ba21743f408617d1269ea1e"

This creates a request using the hosts default personal scheduling preferences.

  1. Use the Cronofy-Impersonate header.

Instead of specifying the host in the payload you can authenticate as specific Account and that will be used as the host of the resulting meeting.

URL format #


Example Request #

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

  "host": {
    "sub": "acc_5ba21743f408617d1269ea1e"
  "recipients": [
      "email": "",
      "display_name": "Marty McFly"
  "collaborator_groups": [
      "name": "Technical Assistant Pool",
      "members": [
        { "sub": "acc_61815034636bd5c5ce4fwd" },
        { "sub": "acc_61815034636bd5c5ce48a4" },
        { "sub": "acc_61815034636bd5c5ce29c7" },
      "required": 1
  "event": {
    "summary": "Driving lessons - Marty & Doc",
    "description": "Don't forget your video camera",
    "location": {
      "description": "Hill Valley"
    "duration": {
      "minutes": 60
    "locale": "en"
  "tags": [
    { "value": "Urgent" },
    { "value": "In-person" }

Example Response #

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

  "scheduler_request": {
    "scheduler_request_id": "srq_64b17b558090ea21640c914a",
    "primary_select_url": "",
    "recipients": [
        "email": "",
        "display_name": "Marty McFly",
        "select_url": ""

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.

host.sub optional  #

A String value representing the sub for the Cronofy Account hosting the resulting event.

The value must represent a member of the Organizational Unit that the Application is linked to.

recipients required  #

An Array of recipients. Only one recipient is supported currently. required  #

A String email address of the recipient of the Scheduler Request.

recipients.display_name optional  #

A String value representing the name of the recipient.

collaborator_groups optional  #

One or more participants (people or resources) who’s availability should be considered alongside the host and invited to the resulting calendar event.

The parameters marked required are only required if a group is specified. required  #

A name for the group that will be used when viewing the request in the Scheduler app.

collaborator_groups.members.sub required  #

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

Available from the Organizational Unit Members and Organizational Unit Resources endpoints.

collaborator_groups.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 to specify the minimum number of the group that must be available.

When selecting members to be included in the resulting calendar event, the system will respect the order of members as presented in the collaborator_groups.members parameter. So, in the case of 1 being required, the first available member for the time chosen will be used.

event required  #

An object with the details of the event you wish to push into the user’s selected calendar.

event.summary required  #

A String of up to 1024 characters to use as the summary, sometimes referred to as the name, of the event.

event.description optional  #

A String of up to 4096 characters to use as the description of the event that will get created in the calendar.

event.location.description optional  #

The plain text String of up to 1024 characters describing the event’s location.

event.duration optional  #

A Duration value representing the duration of the event.

event.locale optional  #

A String value for the locale to use when creating the event. This impacts the localization of generated or templated content added to the event, such as the “Reschedule or decline here:” footer link.

Supported locales are:

  • ar Arabic
  • cs Czech
  • cy Welsh
  • de German
  • en US English (default)
  • es Spanish
  • fr French
  • fr-CA Canadian French
  • he Hebrew
  • it Italian
  • ja Japanese
  • nl Dutch
  • pl Polish
  • pt-BR Brazilian Portuguese
  • ru Russian
  • sv Swedish
  • tr Turkish
  • zh-CN Simplified Chinese
tags optional  #

Array containing one or more tags to associate with the event.

Tags can be used for filtering Requests when viewing the Cronofy dashboard, and when marking events for counting towards availability constraints.

tags is an array of objects, each Tag has a value. If a Tag matching the provided value does not already exist, it will be created.

Tags have the following restrictions:

  • no more than 32 tags
  • tag value character limit is 64
  • restricted characters currently include ;

Response parameters #

scheduler_request_id  #

Cronofy’s unique identifier for the Scheduler Request String.

recipients  #

An Array of recipients. Only one recipient is supported currently.  #

A String email address of the recipient of the Scheduler Request.

recipients.display_name  #

A String value representing the name of the recipient.

recipients.select_url  #

A String URL value for the recipient to visit in order to select a slot.