Create using a Template ^BETA

Description #

Creates a Scheduling Request by referencing a pre-buit template via its sub.

Using templates enables you to quickly initiative scheduling flows without manually specifying availability rules, hosts, event settings and other details within the API call itself. By combining a valid template with recipient details, you can create scheduling requests via the API with minimal input.

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.

Requirements #

To create a scheduling request using a template, you will need:

1. The sub of a template created via the Cronofy Dashboard. You will find the API ID of your templates below Developer Details on the settings page of the Template you are using.

   

2. The slot_selector for the scheduling request.

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

{
  "template": {
    "sub": "sgr_6859758a01b890018ca68795"
  },
  "recipients": [
    {
      "email": "marty@evenitron.com",
      "display_name": "Marty McFly",
      "slot_selector": true
    }
  ]
}

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_66bc6b35a5db6fa4a2db6525" },
          { "sub": "acc_664b3341a5db6f74902348b2" }
        ],
        "required": 1
      }
    ],
    "event": {
      "summary": "Driving lessons - Marty & Doc"
    }
  }
}

Request Parameters #

template.sub required  #

A String value representing the sub for the template that contatins the details that will be used in the Scheduling Request.

The value must represent a template that exists in the Organizational Unit that the Application is linked to.

recipients required  #

An Array containing the one recipient who will be the slot_selector.

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.

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. This will include any setup on the Template.

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.

Viewing the Request #

Once created successfully, your API response will include a dashboard_url that links directly to the generated request within your Cronofy Dashboard.

Template Validation #

Cronofy includes built-in validation to ensure templates used via the API are complete and compatible.

When you create or edit a template in your Cronofy Dashboard, you can assign it the type Scheduling Request via API.

This activates automatic validation that checks whether the template can be used to generate scheduling requests via the API. If required elements are missing, such as a host - an error message will display, along with guidance on what needs to be corrected.

Validation Errors #

If there are any issues with the template or recipients value provided, we will show an error message advising the error.

If the error relates to the template, we will provide a link to the affected template under the field cronofy_dashboard_url which an admin of the Organizational Unit can access to correct the error.

The following validation errors will occur when either the slot_selectoror the recipients field has not been provided.

{
    "errors": {
        "recipients": [
            {
                "key": "errors.required",
                "description": "recipients must be specified"
            }
        ]
    }
}

{
    "errors": {
        "recipients": [
            {
                "key": "errors.slot_selector_required",
                "description": "A single slot_selector must be specified"
            }
        ]
    }
}

The following validation error will occur when the template contains placeholders in the event title or description as these are not supported for the API.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.placeholders_not_supported",
                "description": "Event details contain placeholders that are not supported via the API.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template doesn’t have a host selected.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.host.required",
                "description": "host is required.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template has a host_groupselected that has no members.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.host_group.must_not_be_empty",
                "description": "host_group must have at least one participant.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template has a host that isn’t part of the Organizational Unit you’re authorized against or is not a recognized entity.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.host.not_recognized",
                "description": "host not recognized.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template has a collaborator_groupselected that has no members.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.collaborator_groups.selection_rule_must_not_be_empty",
                "description": "The Selection Rule must have at least one participant.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template is not recognized or deleted.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.not_recognized",
                "description": "template not recognized",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template has a combination of participants whose availability cannot be satisfied.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.unsatisfiable_query_participants",
                "description": "The template contains a collection of participants whose requirements cannot be satisfied.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}

The following validation error will occur when the template has query periods that are in the past.

{
    "errors": {
        "template.sub": [
            {
                "key": "errors.template.availability_mode.query_periods.query_period_in_the_past",
                "description": "The template contains query periods that are in the past.",
                "cronofy_dashboard_url": "https://app.cronofy.com/organizational_units/664b35bca5db6f854be75564/scheduling_rules/67fe29bfa5db6f146940e3d9"
            }
        ]
    }
}