v1
latestOpenAPI 3.0.02026-07-17121287546.7 KBBookings
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.
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 belonging to an individual user:
1. Provide `eventTypeId` in the request body.
2. Provide `eventTypeSlug` and `username` and optionally `organizationSlug` if the user with the username is within an organization.
And 2 ways to book and event type belonging to a team:
1. Provide `eventTypeId` in the request body.
2. Provide `eventTypeSlug` and `teamSlug` and optionally `organizationSlug` if the team with the teamSlug is within an organization.
If you are creating a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or
you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.
For event types that have SMS reminders enabled, you need to pass the attendee's phone number in the request body via `attendee.phoneNumber` (e.g., "+19876543210" in international format). This is an optional field, but becomes required when SMS reminders are enabled for the event type. For the complete attendee object structure, see the attendee schema in the `/docs` Swagger endpoint.
<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>
post/v2/bookings
Headers
cal-api-versionstring required
Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.
Authorizationstring
value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token
x-cal-secret-keystring
For platform customers - OAuth client secret key
x-cal-client-idstring
For platform customers - OAuth client ID
Request body
Example request
{
"start": "2024-08-13T09:00:00Z",
"attendee": {
"name": "John Doe",
"timeZone": "America/New_York",
"phoneNumber": "+919876543210",
"language": "it",
"email": "john.doe@example.com"
},
"bookingFieldsResponses": {
"customField": "customValue"
},
"eventTypeId": 123,
"eventTypeSlug": "my-event-type",
"username": "john-doe",
"teamSlug": "john-doe",
"organizationSlug": "acme-corp",
"guests": [
"guest1@example.com",
"guest2@example.com"
],
"meetingUrl": "https://example.com/meeting",
"location": {
"type": "address"
},
"metadata": {
"key": "value"
},
"lengthInMinutes": 30,
"routing": {
"responseId": 123,
"teamMemberIds": [
101,
102
],
"teamMemberEmail": "john.doe@example.com",
"skipContactOwner": true,
"crmAppSlug": "salesforce",
"crmOwnerRecordType": "Account"
},
"emailVerificationCode": "123456"
}Response
Example response
{
"status": "success",
"data": {
"id": 123,
"uid": "booking_uid_123",
"title": "Consultation",
"description": "Learn how to integrate scheduling into marketplace.",
"hosts": [
{
"id": 1,
"name": "Jane Doe",
"email": "jane100@example.com",
"displayEmail": "jane100@example.com",
"username": "jane100",
"timeZone": "America/Los_Angeles"
}
],
"status": "accepted",
"cancellationReason": "User requested cancellation",
"cancelledByEmail": "canceller@example.com",
"reschedulingReason": "User rescheduled the event",
"rescheduledByEmail": "rescheduler@example.com",
"rescheduledFromUid": "previous_uid_123",
"rescheduledToUid": "new_uid_456",
"start": "2024-08-13T15:30:00Z",
"end": "2024-08-13T16:30:00Z",
"duration": 60,
"eventTypeId": 50,
"eventType": {
"id": 1,
"slug": "some-event"
},
"meetingUrl": "https://example.com/recurring-meeting",
"location": "https://example.com/meeting",
"absentHost": true,
"createdAt": "2024-08-13T15:30:00Z",
"updatedAt": "2024-08-13T15:30:00Z",
"metadata": {
"key": "value"
},
"rating": 4,
"icsUid": "ics_uid_123",
"attendees": [
{
"name": "John Doe",
"email": "john@example.com",
"displayEmail": "john@example.com",
"timeZone": "America/New_York",
"language": "en",
"phoneNumber": "+1234567890"
}
],
"guests": [
"guest1@example.com",
"guest2@example.com"
],
"bookingFieldsResponses": {
"customField": "customValue"
}
}
}