Create BETA

Required plan: Scheduler

Description #

Creates a Scheduling Request using a Cronofy Account or Organizational Unit.

Authentication is with either:

  1. an access token for the Organizational Unit, created by authorizing an application for an Organizational Unit scope like organizational_unit_scheduler
  2. the client_secret of an Internal Application linked to the Organizational Unit.

The API 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 three ways:

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

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

  1. Specify a host_group in the payload. In this case the specific host will be resolved when the time is chosen from the provided options.
{
  "host_group": {
    "name": "Support team",
    "members": [
      { "sub": "acc_61815034636bd5c5ce4fwd" },
      { "sub": "acc_61815034636bd5c5ce48a4" },
      { "sub": "acc_61815034636bd5c5ce29c7" }
    ],
    "required": 1
  }
  ...
}
  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 #

{data_center_url}/v1/scheduling_requests

Example Request #

POST /v1/scheduling_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": "marty@evenitron.com",
      "display_name": "Marty McFly",
      "slot_selector": true
    }
  ],
  "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

{
  "scheduling_request": {
    "scheduling_request_id": "srq_64b17b558090ea21640c914a",
    "slot_selection": "pending",
    "primary_select_url": "https://app.cronofy.com/rts/234ebnd",
    "dashboard_url": "https://app.cronofy.com/scheduler/requests/650b0f4c0d02a8a651b8fc24",
    "summary": "Driving lessons - Marty & Doc",
    "duration": { "minutes": 30 },
    "recipient_operations": {
      "view_url": "https://app.cronofy.com/rts/234ebnd"
    },
    "recipients": [
      {
        "email": "marty@evenitron.com",
        "display_name": "Marty McFly",
        "slot_selector": true
      }
    ],
    "collaborator_groups": [
      {
        "name": "Technical Assistant Pool",
        "members": [
          { "sub": "acc_61815034636bd5c5ce4fwd" },
          { "sub": "acc_61815034636bd5c5ce48a4" },
          { "sub": "acc_61815034636bd5c5ce29c7" }
        ],
        "required": 1
      }
    ],
    "event": {
      "summary": "Driving lessons - Marty & Doc"
    }
  }
}

Request Parameters #

data_center_url required

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

  • api-au.cronofy.com - 🇦🇺 Australia
  • api-ca.cronofy.com - 🇨🇦 Canada
  • api-de.cronofy.com - 🇩🇪 Germany
  • api-sg.cronofy.com - 🇸🇬 Singapore
  • api-uk.cronofy.com - 🇬🇧 United Kingdom
  • api.cronofy.com - 🇺🇸 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.

host_group optional  #

Specifies a group of candidate accounts from which we will choose a host for the event.

The parameters marked required are only required if a host_group is specified.

host_group.name required  #

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

host_group.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.

host_group.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.

Only one member can host the resulting event, but we support requiring more members to simplify use cases where multiple people from a pool are required to attend the event, and any of those members are capable of being the host.

When selecting a member to be chosen to host the resulting calendar event, the system will respect the order of members as presented in the host_group.members parameter. In the case of 2 being required, the first available member for the time chosen will host the event, and the second member will be added as an attendee of that event.

recipients required  #

An Array of recipients.

recipients.email 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.

recipients.slot_selector required  #

A Boolean value representing if this is the user who is expected to choose the time.

Only one recipient should have slot_selector set to true.

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.

collaborator_groups.name 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 ;
disable_email_notifications optional  #

A Boolean value that when true means we will not send any email notifications for this Scheduling Request.

If not provided, defaults to false.

availability_mode optional  #

An object that provides more control over time slot generation for participants. It supports several modes which are specified by availability_mode.mode, and the other required parameters vary by this mode, with examples provided below.

availability_mode.mode required  #

A String that can be one of: working_hours, custom_hours, or specific_slots. Other values may be supported in the future.

working_hours - Enables the sharing of one time period. We’ll generate slot times based on both participants’ calendar availability and their configured working hours over the given period.

  • With scheduling_period specified, shares the next N days of availability.
  • With query_periods specified, shares a specific time range which can start in the future.

In both cases, appropriate slot times will be generated within the shared time period.

  {
    "availability_mode": {
        "mode": "working_hours",
        "scheduling_period": 28
    }
  }
  {
    "availability_mode": {
      "mode": "working_hours",
      "query_periods": [
        {
          "start": "2023-09-21T08:00:00.000Z",
          "end": "2023-10-21T20:00:00.000Z"
        }
      ]
    }
  }

custom_hours - Enables the sharing of one or more time periods, ignoring the participants’ configured working hours, but still considering their busy times.

For instance, if you’re a recruiter wishing to offer time slots from 6pm to 8pm to candidates, you can do so, even if your workday ends at 5pm.

Appropriate slot times will be generated within the shared time periods.

  {
    "availability_mode": {
      "mode": "custom_hours",
      "query_periods": [
        {
          "start": "2023-09-21T18:00:00.000Z",
          "end": "2023-09-21T20:00:00.000Z"
        },
        {
          "start": "2023-09-22T18:00:00.000Z",
          "end": "2023-09-22T20:00:00.000Z"
        },
        {
          "start": "2023-09-23T18:00:00.000Z",
          "end": "2023-09-23T20:00:00.000Z"
        }
      ]
    }
  }

specific_slots - Allows greater control by specifying the exact slot times considered. We ignore participants’ working hours and buffers when checking slots for availability, but still avoid busy times. Slot times may overlap each other.

  {
    "availability_mode": {
      "mode": "specific_slots",
      "query_slots": [
        {
          "start": "2023-09-20T14:15:00Z"
        },
        {
          "start": "2023-09-20T14:45:00Z"
        },
        {
          "start": "2023-09-20T15:00:00Z"
        }
      ]
    }
  }
availability_mode.scheduling_period required  #

This property is only valid when paired with the working_hours mode.

An Integer specifying the number of days in the future to share.

Must be between 1 and 35 inclusive.

availability_mode.query_periods required  #

An array of 1 to 50 periods across up to 35 days in total, each signifying a time range within which potential slots are derived.

This property is valid only with the working_hours or custom_hours modes. For working_hours, provide just one query period. For custom_hours, multiple query periods can be provided.

availability_mode.query_periods.start required  #

The start of a query period as a Time.

It must represent a future point in time.

availability_mode.query_periods.end required  #

The end of a query period as a Time.

Must be at least 1 minute after the corresponding start and within 35 days of the earliest start.

availability_mode.query_slots required  #

An array of 1 to 50 slot times across up to 35 days in total, each of which will be considered for availability.

This property is valid only when paired with the specific_slots mode.

availability_mode.query_slots.start required  #

The start of a query slot as a Time.

It must represent a future point in time. The end is unspecified, as it is implicit based on the duration of the event.

buffer optional  #

A set of Buffer values to that can be used to optionally override participants default buffers configured in their scheduler preferences.

buffer.before optional  #

A Duration specifying the minimum number of minutes that must be free before an available period starts.

buffer.after optional  #

A Duration specifying the minimum number of minutes that must be free after the available period ends.

data_capture optional  #

An Object where additional data capture requirements of the Scheduling Request’s booking flow are specified.

We support capturing a Phone Number field, as well as an arbitrary Notes field, which can have its label overridden.

Captured data is available on the Scheduling Request within the event’s metadata field, present on the Query API or via Workflow Callbacks.

Captured data is saved under the following metadata keys:

  • captured_data.phone_number
  • captured_data.notes
data_capture.phone_number optional  #

A String controlling the display of the Phone Number field, which must be one of:

  • disabled (default) - The field will not be shown
  • optional - The field will be shown, but may be left blank
  • required - The field will be shown, and a value must be entered
data_capture.notes optional  #

A String controlling the display of the Notes field, which must be one of:

  • disabled (default) - The field will not be shown
  • optional - The field will be shown, but may be left blank
  • required - The field will be shown, and a value must be entered
data_capture.notes_title_override optional  #

A String which may be provided to alter the label of the Notes field as shown to the slot selector.

The default label is “Additional information”.

Response parameters #

scheduling_request  #

An Object representing the created Scheduling Request.

scheduling_request.scheduling_request_id  #

Cronofy’s unique identifier for the Scheduling Request String.

scheduling_request.slot_selection  #

A String representing the current state of the Scheduling Request.

Can be one of the following values:

  • pending - Waiting for the slot selector to choose a time slot.
  • pending_rescheduling - The request has been marked as needing to be rescheduled and we are waiting for the slot selector to choose a new time.
  • complete - A time has been selected for the event.
  • expired - The request has been open for too long such that there are no longer any slots within the requests time range.
  • cancelled - Scheduling request was cancelled.
scheduling_request.primary_select_url  #

The URL to the page from which a time can be chosen for the event.

scheduling_request.dashboard_url  #

The URL to the Cronofy dashboard page to view and manage the Scheduling Request.

scheduling_request.summary  #

The String value of the summary, sometimes referred to as the name, of the event.

scheduling_request.recipient_operations  #

An Object containing the URLs for various operations that can be performed on the scheduling request.

scheduling_request.recipient_operations.view_url  #

The URL to the page to view the Scheduling Request.

scheduling_request.recipient_operations.decline_url  #

The URL to the page to decline the Scheduling Request.

scheduling_request.recipient_operations.reschedule_url  #

The URL to the page to reschedule the Scheduling Request.

scheduling_request.recipients  #

An Array of recipients.

scheduling_request.recipients.email  #

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

scheduling_request.recipients.display_name  #

A String value representing the name of the recipient.

scheduling_request.recipients.slot_selector  #

A Boolean value indicating whether or not the recipient is responsible for choosing the time slot for the event.

scheduling_request.event.summary  #

The String value of the summary, sometimes referred to as the name, of the event.