# Create Conversation

> **ALPHA**

#### Description
Creates a Scheduling Conversation in an initial state.

#### URL format
```
{data_center_url}/v1/scheduling_conversations
```

#### Example Request
```http
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": "2026-05-02T09:00:00Z",
      "end": "2026-05-02T18:00:00Z"
    }
  ]
}
```

#### 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).
##### `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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md).
##### `participants.sub`


The internal Cronofy ID for the account, as an ASCII-only [`String`](/developers/api/data-types/index.md).

This can be retrieved by calling the [UserInfo endpoint](/developers/api/identity/userinfo/index.md) 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`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md) representing a known time zone identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).

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

##### `subject` *(optional)*

A [`String`](/developers/api/data-types/index.md) 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](/developers/api/events/upsert-event/index.md) request.

Currently supported options are:

##### `event.location` *(optional)*

Location for the event, [full documenation](/developers/api/events/upsert-event/index.md).

##### `required_duration` *(required)*

A [`Duration`](/developers/api/data-types/index.md) 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)*

The`start` of an available period as a [`Time`](/developers/api/data-types/index.md).

It must represent a future point in time.
##### `available_periods.end` *(required)*


The`end` of an available 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`.



---
[Read in HTML](/developers/api-alpha/scheduling-conversations/create/)