Create a booking
POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except: If eventTypeId in the request body is id of a regular event, then regular booking is created.
If it is an id of a recurring event type, then recurring booking is created.
Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible.
For team event types it is possible to create instant meeting. To do that just pass "instant": true
to the request body.
The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone.
Finally, there are 2 ways to book an event type:
- Provide
eventTypeId
in the request body. - Provide
eventTypeSlug
andusername
and optionallyorganizationSlug
if the user with the username is within an organization.
Headers
Must be set to 2024-08-13
Body
The start time of the booking in ISO 8601 format in UTC timezone.
"2024-08-13T09:00:00Z"
The attendee's details.
If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here. If not provided then event type default length will be used for the booking.
30
The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.
123
The slug of the event type. Required along with username and optionally organizationSlug if eventTypeId is not provided.
"my-event-type"
The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
"john-doe"
The organization slug. Optional, only used when booking with eventTypeSlug + username.
"acme-corp"
An optional list of guest emails attending the event.
Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.
"https://example.com/meeting"
One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.
You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.
{ "key": "value" }
Booking field responses consisting of an object with booking field slug as keys and user response as values.
{ "customField": "customValue" }
The start time of the booking in ISO 8601 format in UTC timezone.
"2024-08-13T09:00:00Z"
The attendee's details.
If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here. If not provided then event type default length will be used for the booking.
30
The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.
123
The slug of the event type. Required along with username and optionally organizationSlug if eventTypeId is not provided.
"my-event-type"
The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
"john-doe"
The organization slug. Optional, only used when booking with eventTypeSlug + username.
"acme-corp"
An optional list of guest emails attending the event.
Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.
"https://example.com/meeting"
One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.
You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.
{ "key": "value" }
Booking field responses consisting of an object with booking field slug as keys and user response as values.
{ "customField": "customValue" }
The start time of the booking in ISO 8601 format in UTC timezone.
"2024-08-13T09:00:00Z"
The attendee's details.
Flag indicating if the booking is an instant booking. Only available for team events.
true
If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here. If not provided then event type default length will be used for the booking.
30
The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.
123
The slug of the event type. Required along with username and optionally organizationSlug if eventTypeId is not provided.
"my-event-type"
The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
"john-doe"
The organization slug. Optional, only used when booking with eventTypeSlug + username.
"acme-corp"
An optional list of guest emails attending the event.
Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.
"https://example.com/meeting"
One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.
You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.
{ "key": "value" }
Booking field responses consisting of an object with booking field slug as keys and user response as values.
{ "customField": "customValue" }
The start time of the booking in ISO 8601 format in UTC timezone.
"2024-08-13T09:00:00Z"
The attendee's details.
If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here. If not provided then event type default length will be used for the booking.
30
The ID of the event type that is booked. Required unless eventTypeSlug and username are provided as an alternative to identifying the event type.
123
The slug of the event type. Required along with username and optionally organizationSlug if eventTypeId is not provided.
"my-event-type"
The username of the event owner. Required along with eventTypeSlug and optionally organizationSlug if eventTypeId is not provided.
"john-doe"
The organization slug. Optional, only used when booking with eventTypeSlug + username.
"acme-corp"
An optional list of guest emails attending the event.
Deprecated - use 'location' instead. Meeting URL just for this booking. Displayed in email and calendar event. If not provided then cal video link will be generated.
"https://example.com/meeting"
One of the event type locations. If instead of passing one of the location objects as required by schema you are still passing a string please use an object.
You can store any additional data you want here. Metadata must have at most 50 keys, each key up to 40 characters, and string values up to 500 characters.
{ "key": "value" }
Booking field responses consisting of an object with booking field slug as keys and user response as values.
{ "customField": "customValue" }
The number of recurrences. If not provided then event type recurrence count will be used. Can't be more than event type recurrence count
5
Was this page helpful?