Create BETA
Required plan: SchedulerDescription #
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.
- 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
}
...
}
- 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
- π¦πΊ Australiaapi-ca.cronofy.com
- π¨π¦ Canadaapi-de.cronofy.com
- π©πͺ Germanyapi-sg.cronofy.com
- πΈπ¬ Singaporeapi-uk.cronofy.com
- π¬π§ United Kingdomapi.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
Arabiccs
Czechcy
Welshde
Germanen
US English (default)es
Spanishfr
Frenchfr-CA
Canadian Frenchhe
Hebrewit
Italianja
Japanesenl
Dutchpl
Polishpt-BR
Brazilian Portugueseru
Russiansv
Swedishtr
Turkishzh-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 shownoptional
- The field will be shown, but may be left blankrequired
- 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 shownoptional
- The field will be shown, but may be left blankrequired
- 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.