Getting Started
Platform / Managed Users
Platform / Webhooks
Orgs / Attributes
Orgs / Attributes / Options
- GETGet all attribute options
- POSTCreate an attribute option
- DELDelete an attribute option
- PATCHUpdate an attribute option
- GETGet by attribute id all of the attribute options that are assigned to users
- GETGet by attribute slug all of the attribute options that are assigned to users
- GETGet all attribute options for a user
- POSTAssign an attribute to a user
- DELUnassign an attribute from a user
Orgs / Bookings
Orgs / Delegation Credentials
Orgs / Memberships
Orgs / Routing forms
Orgs / Schedules
Orgs / Teams
Orgs / Teams / Bookings
Orgs / Teams / Conferencing
- POSTConnect your conferencing application to a team
- GETGet OAuth conferencing app's auth url for a team
- GETList team conferencing applications
- POSTSet team default conferencing application
- GETGet team default conferencing application
- DELDisconnect team conferencing application
- GETSave conferencing app OAuth credentials
Orgs / Teams / Event Types
Orgs / Teams / Memberships
Orgs / Teams / Routing forms
Orgs / Teams / Routing forms / Responses
Orgs / Teams / Users / Schedules
Orgs / Users / Bookings
Orgs / Users / OOO
Orgs / Users / Schedules
Orgs / Webhooks
Api Keys
Bookings
- GETGet all bookings
- POSTCreate a booking
- GETGet a booking
- POSTReschedule a booking
- POSTCancel a booking
- POSTMark a booking absence
- POSTReassign a booking to auto-selected host
- POSTReassign a booking to a specific host
- POSTConfirm a booking
- POSTDecline a booking
- GETGet 'Add to Calendar' links for a booking
- GETGet 'Booking References' for a booking
Calendars
Conferencing
Destination Calendars
Event Types
Event Types / Webhooks
Managed Orgs
OAuth Clients
Organization Team Verified Resources
- POSTRequest Email Verification Code
- POSTRequest Phone Number Verification Code
- POSTVerify an email for an org team.
- POSTVerify a phone number for an org team.
- GETGet list of verified emails of an org team.
- GETGet list of verified phone numbers of an org team.
- GETGet verified email of an org team by id.
- GETGet verified phone number of an org team by id.
Organizations/Teams Stripe
Routing forms
Schedules
Selected Calendars
Slots
Teams / Event Types
Teams / Memberships
Teams Verified Resources
- POSTRequest Email Verification Code
- POSTRequest Phone Number Verification Code
- POSTVerify an email for a team.
- POSTVerify a phone number for an org team.
- GETGet list of verified emails of a team.
- GETGet list of verified phone numbers of a team.
- GETGet verified email of a team by id.
- GETGet verified phone number of a team by id.
Verified Resources
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 belonging to an individual user:
- Provide
eventTypeId
in the request body. - Provide
eventTypeSlug
andusername
and optionallyorganizationSlug
if the user with the username is within an organization.
And 2 ways to book and event type belonging to a team:
- Provide
eventTypeId
in the request body. - Provide
eventTypeSlug
andteamSlug
and optionallyorganizationSlug
if the team with the teamSlug is within an organization.
curl --request POST \
--url https://api.cal.com/v2/bookings \
--header 'Content-Type: application/json' \
--header 'cal-api-version: <cal-api-version>' \
--data '{
"start": "2024-08-13T09:00:00Z",
"attendee": {
"name": "John Doe",
"email": "john.doe@example.com",
"timeZone": "America/New_York",
"phoneNumber": "+919876543210",
"language": "it"
},
"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
}'
{
"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",
"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",
"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.doe@example.com",
"timeZone": "America/New_York",
"phoneNumber": "+919876543210",
"language": "it"
}
],
"guests": [
"guest1@example.com",
"guest2@example.com"
],
"bookingFieldsResponses": {
"customField": "customValue"
}
}
}
Headers
Must be set to 2024-08-13
Body
The body is of type object
.
The body is of type object
.
The body is of type object
.
The body is of type object
.
Response
The response is of type object
.
Was this page helpful?
curl --request POST \
--url https://api.cal.com/v2/bookings \
--header 'Content-Type: application/json' \
--header 'cal-api-version: <cal-api-version>' \
--data '{
"start": "2024-08-13T09:00:00Z",
"attendee": {
"name": "John Doe",
"email": "john.doe@example.com",
"timeZone": "America/New_York",
"phoneNumber": "+919876543210",
"language": "it"
},
"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
}'
{
"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",
"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",
"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.doe@example.com",
"timeZone": "America/New_York",
"phoneNumber": "+919876543210",
"language": "it"
}
],
"guests": [
"guest1@example.com",
"guest2@example.com"
],
"bookingFieldsResponses": {
"customField": "customValue"
}
}
}