Create ^BETA

Description #

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

Authentication is with either:

an access token for the Organizational Unit, created by authorizing an application for an Organizational Unit scope like organizational_unit_scheduler
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:

Specify host in the payload.

{
  "host": {
    "sub": "acc_5ba21743f408617d1269ea1e"
  },
  ...
}

This creates a request using the hosts default personal scheduling preferences, unless you pass an availability_mode.

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.

This can either be described completely in the API call.

{
  "host_group": {
    "name": "Support team",
    "members": [
      { "sub": "acc_61815034636bd5c5ce4fwd" },
      { "sub": "acc_61815034636bd5c5ce48a4" },
      { "sub": "acc_61815034636bd5c5ce29c7" }
    ],
    "required": 1
  }
  ...
}

or by referencing a Selection Rule already defined in the Organizational Unit.

{
  "host_group": {
    "sub": "sel_61815034636bd5c5ce40d",
  }
  ...
}

This creates a request using a default period of 14 days unless you pass an availability_mode.

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"
  },
  "minimum_notice": {
    "hours": 12
  },
  "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.sub optional #

The API ID for a Selection Rule from the Scheduler app. You can obtain this in the Developer Details section at the foot of the Selection Rule management page.

If this is specified then no other host_group parameters are supported.

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.

Note that when a group requires only some of the members, the order the members are listed in will be used as a soft-preference for who is selected. If you want to evenly distribute events to members across several requests, you should shuffle this list so each request has the members in a random order.

collaborator_groups.required required #

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

minimum_notice optional #

A Duration. The user selecting slots will not be offered any times that are within this period following the time of selection.

By default, the minimum notice will be determined based on the host and collaborators’ Scheduler preferences. Specifying a value for the Request explicitly will override any preferences.

The maximum minimum notice is 48 hours.

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.

If no availability_mode is passed we set the availability based on the personal scheduling preferences of the host. If you set a host_group instead of host we will default to a period of 14 days.

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.

availability_mode.selection_format optional #

A String that can be one of: overlapping_slots or discrete_slots. Other values may be supported in the future. The default behavior if not specified is overlapping_slots.

This value is not accepted in the specific_slots Availability Mode.

The provided value influences the slot times we will generate:

In the default overlapping_slots behavior, slots may be offered at times that overlap with each other. For example, given a 90-minute event duration, and a query period covering three hours from 8AM - 11AM, we would offer slots starting at 8AM, 8:30AM, 9AM, and 9:30AM.
The discrete_slots format does not allow offered slot times to overlap. For the same scenario above, we would offer slots starting at 8AM and 9:30AM only.

Your use case will influence your preference; It can be seen as a trade-off between more choice for the slot selector, or keeping hosts’ calendars more tightly packed to leave room for multiple bookings.

In the overlapping_slots case, the recipient has more options to choose from and may be more likely to find a time that suits them. However, if they choose a slot time in the middle of the 3-hour window, a subsequent second 90-minute meeting with the same constraints would no longer be possible.

In the discrete_slots case, the recipient would only be offered times that allowed a second 90-minute meeting to fit alongside.

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.

Validation Errors #

The following validation error can occur when integrated conferencing is no longer available for an account.

{
    "errors": {
        "target_calendars[0].calendar_id": [
            {
                "key": "errors.integrated_conferencing_not_available",
                "description": "Integrated conferencing is not available on this calendar"
            }
        ]
    }
}

This can occur when an account is initially provisioned with integrated conferencing, but this feature is subsequently removed from the calendar at the provider (Google/Microsoft etc) level.

This can be resolved by identifying which account in the request has misconfigured conferencing via UserInfo, and directing the user to update their Cronofy Scheduler preferences. The currently selected Conferencing service can be updated by navigating to the ‘Event Details’ tab, choosing an available conferencing option, and clicking the ‘Save’ button.

Create BETA

Description #

URL format #

Example Request #

Example Response #

Request Parameters #

data_center_url required

host.sub optional #

host_group optional #

host_group.sub optional #

host_group.name required #

host_group.members.sub required #

host_group.required required #

recipients required #

recipients.email required #

recipients.display_name optional #

recipients.slot_selector required #

collaborator_groups optional #

collaborator_groups.name required #

collaborator_groups.members.sub required #

collaborator_groups.required required #

event required #

event.summary required #

event.description optional #

event.location.description optional #

event.duration optional #

event.locale optional #

minimum_notice optional #

tags optional #

disable_email_notifications optional #

availability_mode optional #

availability_mode.mode required #

availability_mode.scheduling_period required #

availability_mode.query_periods required #

availability_mode.query_periods.start required #

availability_mode.query_periods.end required #

availability_mode.query_slots required #

availability_mode.query_slots.start required #

availability_mode.selection_format optional #

buffer optional #

buffer.before optional #

buffer.after optional #

data_capture optional #

data_capture.phone_number optional #

data_capture.notes optional #

data_capture.notes_title_override optional #

Response parameters #

scheduling_request #

scheduling_request.scheduling_request_id #

scheduling_request.slot_selection #

scheduling_request.primary_select_url #

scheduling_request.dashboard_url #

scheduling_request.summary #

scheduling_request.recipient_operations #

scheduling_request.recipient_operations.view_url #

scheduling_request.recipient_operations.decline_url #

scheduling_request.recipient_operations.reschedule_url #

scheduling_request.recipients #

scheduling_request.recipients.email #

scheduling_request.recipients.display_name #

scheduling_request.recipients.slot_selector #

scheduling_request.event.summary #

Validation Errors #

Create ^BETA