Create Conversation ^ALPHA

Description #

Creates a Scheduling Conversation in an initial state.

URL format #

{data_center_url}/v1/scheduling_conversations

Example Request #

POST /v1/scheduling_conversations HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "participants": [
    {
      "participant_id": "@grace",
      "sub": "acc_5ba21743f408617d1269ea1e",
      "email": "grace@company.com",
      "common_name": "Grace Devlin",
      "managed_availability": true,
      "slots": {
        "selection_method": "auto"
      }
    },
    {
      "participant_id": "@karl",
      "common_name": "Karl Cramer"
    }
  ],
  "tzid": "America/Chicago",
  "subject": "Project Titan review",
  "event": {
    "location": {
      "description": "Board Room"
    }
  },
  "required_duration": {
    "minutes": 60
  },
  "available_periods": [
    {
      "start": "2024-12-23T09:00:00Z",
      "end": "2024-12-23T18:00:00Z"
    }
  ]
}

Request parameters #

participants required  #

An array of the groups of participants who will participate in this scheduling conversation.

Identification of participants is through one of three properties in the following order of importance: participant_id, sub then email. At least one of these must be supplied.

Currently, the maximum number of participants is two.

The first participant is considered the organizer of the event.

At least one of the following participant_id, sub or email is required to uniquely identify a participant.

participants.participant_id  #

The String that uniquely identifies the participant in the calling application.

Usually this will be your own internal ID for the participant, eg @grace, encoded as a String.

participants.sub  #

The internal Cronofy ID for the account, as an ASCII-only String.

This can be retrieved by calling the UserInfo endpoint with a valid access_token

participants.email  #

An email address for the participant. This will be used to identify a scheduling conversation service the participant has enabled to progress the conversation, and/or progress the conversation via email.

participants.common_name  #

Friendly name for the participant. Required for the first participant which is considered the organizer.

participants.managed_availability  #

Boolean. Default if not supplied is false.

This indicates whether an availability lookup for the the participant should should use the Availability Rules or Available Periods stored against their Cronofy account.

participants.slots.selection_method  #

auto or manual. Default if not supplied is manual.

This indicates whether the participant should be prompted to choose a slot or (manual) or use their availability to automatically find a time (auto).

tzid required  #

Specifies the master timezone for the conversation. A String representing a known time zone identifier from the IANA Time Zone Database.

This will be used as the default timezone for any events created in participant’s calendars.

subject optional  #

A String providing a human readable description of the topic of the event being scheduled.

event optional  #

A series of parameters providing template values for any events that are created as a result of the scheduling conversation.

They are subset of all the parameters have the same meaning as documented in the Create or Update Event request.

Currently supported options are:

event.location optional  #

Location for the event, full documenation.

required_duration required  #

A Duration describing the minimum period that the participant groups must be satisfied for a period to be deemed as available.

Must be greater than zero minutes in length.

available_periods required  #

An array of 1 to 10 available periods, across up to 35 days of the period of synchronized events, within which suitable matches may be found.

available_periods.start required  #

Thestart of an available period as a Time.

It must represent a future point in time.

available_periods.end required  #

Theend of an available period as a Time.

Must be at least 1 minute after the corresponding start and within 35 days of the earliest start.