Bookings

On this page, we’ll dive into how to manage Bookings within a Booking Link through the OneCal API.

POST/v1/bookings/create

Create a booking

This endpoint creates a new booking using a specified booking link. The request body requires the booking link ID, start date and time, timezone, attendee details, and any custom field responses. Upon successful creation, the response returns the unique booking ID.

Request Body

Name
bookingLinkId
Type
string
Description
The unique identifier of the booking link.
Name
startDateTime
Type
string
Description
The start date and time of the booking in ISO 8601 format.
Name
timezone
Type
string
Description
The timezone for the booking (e.g., "Europe/Rome").
Name
attendees
Type
array
Description
An array of attendees, each containing an email, name, and a boolean indicating if they are a guest.
Name
durationId
Type
string
Description
Optional. The ID of the selected duration for the booking. If not provided, the first duration will be used.
Name
customFieldResponses
Type
array
Description
An array of responses for custom fields related to the booking.

Request

POST

/v1/bookings/create

curl -X POST https://app.onecal.io/api/v1/bookings/create \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingLinkId": "cm6gm7rl1000cpjl5erzxvc6r",
    "startDateTime": "2025-02-25T10:30:00.000Z",
    "timezone": "Europe/Rome",
    "attendees": [{
      "email": "example@email.com",
      "name": "John Doe",
      "isGuest": false
    }],
    "customFieldResponses": [{
      "field": {
        "id": "additionalNotes",
        "name": "additionalNotes",
        "type": "LONG_TEXT",
        "label": "Additional Notes",
        "required": false,
        "placeholder": "Please share anything that will help prepare for our meeting."
      },
      "value": "This is an additional note"
    }]
  }'

Response

{
  "id": "cm7ewkgxl0003pj9acsx0vy66"
}