Booking Links

On this page, we’ll dive into how to manage your team's Booking Links programmatically in OneCal.

The Booking Link model

Properties

Name
id
Type
string
Description
Unique identifier for the booking link.
Name
createdAt
Type
timestamp
Description
Timestamp when the booking link was created.
Name
updatedAt
Type
timestamp
Description
Timestamp when the booking link was last updated.
Name
slug
Type
string
Description
URL-friendly identifier for the booking link.
Name
type
Type
enum
Description
Type of the booking link. Possible values: MULTI_USE, COLLECTIVE_MULTI_USE.
Name
title
Type
string
Description
Title of the booking link.
Name
description
Type
string
Description
Description for the booking link as HTML (nullable).
Name
status
Type
enum
Description
Status of the booking link. Possible values: ENABLED, DISABLED.
Name
bufferMinutesBeforeEvent
Type
number
Description
Buffer time in minutes to apply before the start of existing calendar events.
Name
bufferMinutesAfterEvent
Type
number
Description
Buffer time in minutes to apply after the end of existing calendar events.
Name
eventColor
Type
string
Description
Event color identifier for bookings created from this link (nullable).
Name
eventNameTemplate
Type
string
Description
Template used to generate event names.
Name
allowGuestInvitations
Type
boolean
Description
Flag indicating if guest invitations are allowed.
Name
maxGuestsAllowed
Type
number
Description
Maximum number of guests allowed.
Name
requireEventApproval
Type
boolean
Description
Flag indicating if events require approval.
Name
confirmationMessage
Type
string
Description
Confirmation message displayed after booking (nullable).
Name
redirectUrl
Type
string
Description
URL to redirect to after booking (nullable).
Name
isPrivate
Type
boolean
Description
Flag indicating if the booking link is private. Private links are not displayed in the booking page.
Name
deletedAt
Type
timestamp
Description
Timestamp when the booking link was deleted (nullable).
Name
customFields
Type
array
Description
Array of custom field objects.
Name
disabledBySystem
Type
boolean
Description
Flag indicating if the booking link is disabled by the system.
Name
position
Type
number
Description
Position or order of the booking link relative to other booking links within the same booking page. Used to sort the booking links in the booking page.
Name
minNoticePeriodId
Type
string
Description
Identifier for the minimum notice period (nullable).
Name
minDate
Type
timestamp
Description
Minimum date allowed for booking (nullable).
Name
maxFuturePeriodId
Type
string
Description
Identifier for the maximum future period (nullable).
Name
maxDate
Type
timestamp
Description
Maximum date allowed for booking (nullable).
Name
slotIntervalMinutes
Type
number
Description
Time interval in minutes for booking slots (nullable). If not set, the booking link duration will be used.
Name
coverImageUrl
Type
string
Description
URL for the cover image (nullable). If set, will take precedence over the booking page's cover image.
Name
brandColor
Type
string
Description
Brand color associated with the booking link (nullable). If set, will take precedence over the booking page's branding color.
Name
brandingPreference
Type
enum
Description
Branding preference. Possible values: GLOBAL, CUSTOM, OFF.
Name
language
Type
enum
Description
Language for the booking link (nullable). Possible values: EN,DE,ES,JA,IT. If set, will take precedence over the booking page's language.
Name
languagePreference
Type
enum
Description
Language preference. Possible values: GLOBAL, CUSTOM, OFF.
Name
userId
Type
string
Description
Identifier of the user who owns the booking link.
Name
bookingPageId
Type
string
Description
Identifier of the booking page that the booking link belongs to.
Name
bookingDurations
Type
array
Description
Array of booking duration objects.
Name
maxFuturePeriod
Type
object
Description
Object containing details for the maximum future period (nullable).
Name
minNoticePeriod
Type
object
Description
Object containing details for the minimum notice period (nullable).
Name
hosts
Type
array
Description
Array of host objects associated with the booking link.
Name
bookingPage
Type
object
Description
Object containing details of the booking page.
Name
bookingLocations
Type
array
Description
Array of booking location objects.

How to retrieve a Booking Link ID

To retrieve the ID of a booking link within your OneCal Team, follow these steps:

Navigate to your Team Dashboard.
Click on the user who owns the booking link.
Under the "Booking Links" section, you will see a list of booking links. Find the booking link you are interested in and click on the 3-dot menu on the right.
Click on "Copy ID".

GET/v1/booking-links/:id

This endpoint retrieves detailed information about a specific booking link using its unique identifier. The response includes configuration details such as event settings, custom fields, booking durations, associated hosts, booking page details, and booking locations.

Path Parameter

Name
id
Type
string
Description
The unique identifier of the booking link.

Request

GET

/v1/booking-links/:id

curl -X GET https://app.onecal.io/api/v1/booking-links/{id} \
  -H "x-api-key: {apiKey}"

Response

{
  "id": "cm6gm7rl1000cpjl5erzxvc6r",
  "createdAt": "2025-01-28T15:11:16.837Z",
  "updatedAt": "2025-02-21T12:19:24.410Z",
  "slug": "individual-link",
  "type": "MULTI_USE",
  "title": "Individual Link",
  "description": "",
  "status": "ENABLED",
  "bufferMinutesBeforeEvent": 10,
  "bufferMinutesAfterEvent": 10,
  "eventColor": null,
  "eventNameTemplate": "{{organizer}} and {{scheduler}}",
  "allowGuestInvitations": true,
  "maxGuestsAllowed": 5,
  "requireEventApproval": true,
  "confirmationMessage": null,
  "redirectUrl": null,
  "isPrivate": false,
  "deletedAt": null,
  "customFields": [
    {
      "id": "additionalNotes",
      "name": "additionalNotes",
      "type": "LONG_TEXT",
      "label": "Additional Notes",
      "required": false,
      "placeholder": "Please share anything that will help prepare for our meeting."
    }
  ],
  "disabledBySystem": false,
  "position": 0,
  "minNoticePeriodId": "cm6gm7rks000apjl5j3vfuy46",
  "minDate": null,
  "maxFuturePeriodId": null,
  "maxDate": null,
  "slotIntervalMinutes": null,
  "coverImageUrl": null,
  "brandColor": null,
  "brandingPreference": "GLOBAL",
  "language": null,
  "languagePreference": "GLOBAL",
  "userId": "cm6f15gic0002pj63jc6vqz7d",
  "bookingPageId": "cm6gm3z1r0001pjl5vz95kqr4",
  "bookingDurations": [
    {
      "id": "cm7eqn6gj0002pj1l55ndhlkg",
      "createdAt": "2025-02-21T12:19:24.403Z",
      "updatedAt": "2025-02-21T12:19:24.403Z",
      "durationInMinutes": 30,
      "isDefault": true,
      "bookingLinkId": "cm6gm7rl1000cpjl5erzxvc6r"
    }
  ],
  "maxFuturePeriod": null,
  "minNoticePeriod": {
    "id": "cm6gm7rks000apjl5j3vfuy46",
    "createdAt": "2025-01-28T15:11:16.829Z",
    "updatedAt": "2025-01-29T22:36:12.319Z",
    "unit": "HOUR",
    "quantity": 2
  },
  "hosts": [
    {
      "id": "cm6gm7rl6000epjl55fovjaws",
      "createdAt": "2025-01-28T15:11:16.843Z",
      "updatedAt": "2025-02-21T12:19:24.413Z",
      "isOrganizer": true,
      "readAvailabilityFrom": "ALL_CALENDARS",
      "userId": "cm6f15gic0002pj63jc6vqz7d",
      "bookingLinkId": "cm6gm7rl1000cpjl5erzxvc6r",
      "bookingCalendarId": "cm6f33jtl0007pj6mf2bk5gph",
      "scheduleId": "cm6gm3z590003pjl59g66eo47",
      "schedule": {
        "id": "cm6gm3z590003pjl59g66eo47",
        "createdAt": "2025-01-28T15:08:20.013Z",
        "updatedAt": "2025-01-30T16:02:42.800Z",
        "name": "Working Hours",
        "availability": {
          "friday": [
            {
              "end": "14:00:00",
              "start": "10:00:00"
            },
            {
              "end": "18:00:00",
              "start": "15:00:00"
            }
          ],
          "monday": [
            {
              "end": "14:00:00",
              "start": "10:00:00"
            },
            {
              "end": "18:00:00",
              "start": "15:00:00"
            }
          ],
          "sunday": [],
          "tuesday": [
            {
              "end": "14:00:00",
              "start": "10:00:00"
            },
            {
              "end": "18:00:00",
              "start": "15:00:00"
            }
          ],
          "saturday": [],
          "thursday": [
            {
              "end": "14:00:00",
              "start": "10:00:00"
            },
            {
              "end": "18:00:00",
              "start": "15:00:00"
            }
          ],
          "wednesday": [
            {
              "end": "14:00:00",
              "start": "10:00:00"
            },
            {
              "end": "18:00:00",
              "start": "15:00:00"
            }
          ]
        },
        "timeZone": "Europe/Tirane",
        "isDefault": true,
        "userId": "cm6f15gic0002pj63jc6vqz7d"
      },
      "availabilityCalendars": [],
      "user": {
        "id": "cm6f15gic0002pj63jc6vqz7d",
        "name": "Super Admin",
        "email": "email@example.com",
        "emailVerified": "2025-02-17T18:02:34.710Z",
        "image": "https://api.dicebear.com/7.x/bottts-neutral/svg?seed=cm6f15gi40000pj63ko2umzww",
        "createdAt": "2025-01-27T12:33:51.060Z",
        "updatedAt": "2025-02-17T18:02:34.711Z",
        "status": "ACTIVE",
        "onboardingComplete": true,
        "referral": null,
        "hasAddedTrialReminder": false,
        "hourFormat": "SYSTEM_DEFAULT",
        "firstDayOfWeek": "SYSTEM_DEFAULT",
        "locale": "EN",
        "workspaceId": "cm6f15gi40000pj63ko2umzww"
      }
    }
  ],
  "bookingPage": {
    "id": "cm6gm3z1r0001pjl5vz95kqr4",
    "createdAt": "2025-01-28T15:08:19.887Z",
    "updatedAt": "2025-02-19T12:42:25.155Z",
    "username": "username",
    "descripton": null,
    "status": "ENABLED",
    "hideOnecalBanner": false,
    "isDefault": true,
    "coverImageUrl": null,
    "brandColor": null,
    "language": "DE",
    "defaultCalendarId": "cm6f33jtl0007pj6mf2bk5gph",
    "userId": "cm6f15gic0002pj63jc6vqz7d"
  },
  "bookingLocations": [
    {
      "id": "cm7eqn6go0003pj1l3ypo9brt",
      "createdAt": "2025-02-21T12:19:24.408Z",
      "updatedAt": "2025-02-21T12:19:24.408Z",
      "type": "CALENDAR_DEFAULT",
      "location": "",
      "bookingLinkId": "cm6gm7rl1000cpjl5erzxvc6r",
      "conferenceProviderId": null
    }
  ]
}

GET/v1/booking-links/:id/time-slots

Get time slots for a booking link

This endpoint retrieves the available time slots for a specific booking link. You can optionally specify a startDate and endDate to get the available slots for a specific date range. Additionally, you can specify a durationId to get time slots for a specific duration if multiple durations are supported.

Optional Query Parameters

Name
startDate
Type
timestamp
Description
The starting timestamp to filter available slots. Defaults to the current date and time.
Name
endDate
Type
timestamp
Description
The ending timestamp to filter available slots. Defaults to the end of the current month.
Name
durationId
Type
string
Description
The ID of the selected duration if the link has multiple durations.

Request

GET

/v1/booking-links/:id/time-slots

curl -X GET "https://app.onecal.io/api/v1/booking-links/{id}/time-slots?startDate=2025-02-25T00:00:00.000Z&endDate=2025-02-25T23:59:59.000Z&durationId={durationId}" \
  -H "x-api-key: {apiKey}"

Response

{
  "availableSlots": [
    {
      "start": "2025-02-25T10:30:00.000Z",
      "end": "2025-02-25T11:00:00.000Z"
    },
    {
      "start": "2025-02-25T11:00:00.000Z",
      "end": "2025-02-25T11:30:00.000Z"
    },
    {
      "start": "2025-02-25T11:30:00.000Z",
      "end": "2025-02-25T12:00:00.000Z"
    }
  ]
}

Booking Links

The Booking Link model

Properties

How to retrieve a Booking Link ID

Get a booking link

Path Parameter

Request

Response

Get time slots for a booking link

Optional Query Parameters

Request

Response