# Create #### 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](/developers/authorization/organization-connect/index.md) like `organizational_unit_scheduler` - the `client_secret` of an [Internal Application](/developers/application-management/internal-applications/index.md) 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. ```json { "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. ```json { "host_group": { "name": "Support team", "members": [ { "sub": "acc_61815034636bd5c5ce4fwd" }, { "sub": "acc_61815034636bd5c5ce48a4" }, { "sub": "acc_61815034636bd5c5ce29c7" } ], "required": 1 } ... } ``` or by referencing a [Selection Rule](/scheduler/scheduling-groups-and-rules/index.md) already defined in the Organizational Unit. ```json { "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 ```http 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 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](/developers/data-centers/index.md). ##### `host.sub` *(optional)* A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md). Available from the [Organizational Unit Members](/developers/api-alpha/organizational-unit-members/index.md) and [Organizational Unit Resources](/developers/api-alpha/organizational-unit-resources/index.md) endpoints. ##### `host_group.required` *(required)* Either a [`String`](/developers/api/data-types/index.md) of `all` to specify that all `members` of the group need to be available for a period to be viable, or an [`Integer`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) email address of the recipient of the Scheduler Request. ##### `recipients.display_name` *(optional)* A [`String`](/developers/api/data-types/index.md) value representing the name of the recipient. ##### `recipients.slot_selector` *(required)* A [`Boolean`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md). Available from the [Organizational Unit Members](/developers/api-alpha/organizational-unit-members/index.md) and [Organizational Unit Resources](/developers/api-alpha/organizational-unit-resources/index.md) 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`](/developers/api/data-types/index.md) of `all` to specify that all `members` of the group need to be available for a period to be viable, or an [`Integer`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) of up to 1024 characters to use as the summary, sometimes referred to as the name, of the event. ##### `event.description` *(optional)* A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) of up to 1024 characters describing the event's location. ##### `event.duration` *(optional)* A [`Duration`](/developers/api/data-types/index.md) value representing the duration of the event. ##### `event.locale` *(optional)* A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md). 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](/scheduler/scheduler-constraints/index.md). `tags` is an array of objects, each [`Tag`](/developers/api/data-types/index.md) has a `value`. If a [`Tag`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) that can be one of: `working_hours`, `custom_hours`, `specific_slots`, or `interview`. 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. ```json { "availability_mode": { "mode": "working_hours", "scheduling_period": 28 } } ``` ```json { "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. ```json { "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. ```json { "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" } ] } } ``` `interview` - Enables the sharing of Interview time period that the members have set within Organizational Unit Members Dashboard. We'll generate slot times based on both participants' calendar availability and their configured interview times over the given period. ```json { "availability_mode": { "mode": "interview", "scheduling_period": 7 } } ``` ##### `availability_mode.scheduling_period` *(required)* This property is only valid when paired with the `working_hours` mode. An [`Integer`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md). It must represent a future point in time. ##### `availability_mode.query_periods.end` *(required)* The `end` of a query period as a [`Time`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md). It must represent a future point in time. The `end` is unspecified, as it is implicit based on the [duration of the event](#param-event.duration). ##### `availability_mode.selection_format` *(optional)* A [`String`](/developers/api/data-types/index.md) 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`](/developers/scheduling/buffers/index.md) values to that can be used to optionally override participants default buffers configured in their scheduler preferences. ##### `buffer.before` *(optional)* A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free before an available period starts. ##### `buffer.after` *(optional)* A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free after the available period ends. ##### `data_capture` *(optional)* An [`Object`](/developers/api/data-types/index.md) 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](/developers/api/scheduling-requests/query/index.md) or via [Workflow Callbacks](/scheduler/workflows/index.md). Captured data is saved under the following metadata keys: - `captured_data.phone_number` - `captured_data.notes` ##### `data_capture.phone_number` *(optional)* A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) representing the created Scheduling Request. ##### `scheduling_request.scheduling_request_id` Cronofy's unique identifier for the Scheduling Request [`String`](/developers/api/data-types/index.md). ##### `scheduling_request.slot_selection` A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) value of the summary, sometimes referred to as the name, of the event. ##### `scheduling_request.recipient_operations` An [`Object`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) email address of the recipient of the Scheduler Request. ##### `scheduling_request.recipients.display_name` A [`String`](/developers/api/data-types/index.md) value representing the name of the recipient. ##### `scheduling_request.recipients.slot_selector` A [`Boolean`](/developers/api/data-types/index.md) value indicating whether or not the recipient is responsible for choosing the time slot for the event. ##### `scheduling_request.event.summary` The [`String`](/developers/api/data-types/index.md) value of the summary, sometimes referred to as the name, of the event. #### Available Template Placeholders - {{ cronofy.conferencing.join_url }} The URL to join the conference, for example `https://example.com/join/meeting-abc` - {{ cronofy.conferencing.invite_block }} A multi-line block containing the full invite details of the conference. If dial-in details are available, they will appear in this block. This varies by provider. Content generated by the provider is used where possible. A loose example is: ``` You've been invited to a conference via ExampleConf! You can join here: http://example.com/conferencing/meeting-abc Dial in numbers are available for the following countries: - US: +1-202-555-0169 - UK: +44 1632 960647 - DE: +49 30 419916934 Meeting passcode: 123456``` This value is not accepted in the `location.description` field. - {{ cronofy.scheduling.captured_data.notes }} The information that was entered in [the Notes field](/developers/api/scheduling-requests/create/index.md) if available. By default, the prompt for the Notes field is 'Additional Information'. You can change this prompt to describe the information that you need from people picking a time via the [data_capture.notes_title_override parameter](/developers/api/scheduling-requests/create/index.md) when creating the request. - {{ cronofy.scheduling.captured_data.phone_number }} The information that was entered in [the Phone Number field](/developers/api/scheduling-requests/create/index.md) if available. #### Example Request ```http 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. \n Phone number: {{ cronofy.scheduling.captured_data.phone_number }}\n Reason for call: {{ cronofy.scheduling.captured_data.notes }}", "location": { "description": "Online: {{ cronofy.conferencing.join_url }}" }, "duration": { "minutes": 60 }, "locale": "en" }, "minimum_notice": { "hours": 12 }, "tags": [ { "value": "Urgent" }, { "value": "In-person" } ], "data_capture": { "notes_title_override": "Reason for call", "notes": "required", "phone_number": "required" } } ``` #### Example Response ```http HTTP/1.1 202 Accepted ``` #### Validation Errors The following validation error can occur when integrated conferencing is no longer available for an account. ```json { "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](/developers/api/identity/userinfo/index.md), and directing the user to [update their Cronofy Scheduler preferences](https://app.cronofy.com/jump/scheduler_settings). 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. --- [Read in HTML](/developers/api/scheduling-requests/create/)