Create ^BETA

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.

2. 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
  }
  ...
}

3. 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 #

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.

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  #

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

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.

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.