For AI agents: markdown of this page — /docs-content-en/entities/bookings/create.md documentation index — /llms.txt

Create a booking

POST /v1/bookings

Creates a new booking on the Bitrix24 account. Fields are passed flat at the root of the JSON.

Request fields (body)

Field Type Required Description
resourceIds number[] yes Ids of the resources the booking reserves. The array cannot be empty. The resource list cannot be fetched through the Vibecode API — specify the known ids
datePeriod object yes Booking period. Structure: from and to, each with timestamp (Unix seconds) and timezone (IANA-format time zone, e.g. UTC)
name string no Booking name. May be null
description string no Booking description. May be null

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bookings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceIds": [1],
    "datePeriod": {
      "from": { "timestamp": 1780132384, "timezone": "UTC" },
      "to":   { "timestamp": 1780135984, "timezone": "UTC" }
    },
    "name": "Meeting room for the demo",
    "description": "Meeting room booking"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bookings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceIds": [1],
    "datePeriod": {
      "from": { "timestamp": 1780132384, "timezone": "UTC" },
      "to":   { "timestamp": 1780135984, "timezone": "UTC" }
    },
    "name": "Meeting room for the demo",
    "description": "Meeting room booking"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resourceIds: [1],
    datePeriod: {
      from: { timestamp: 1780132384, timezone: 'UTC' },
      to:   { timestamp: 1780135984, timezone: 'UTC' },
    },
    name: 'Meeting room for the demo',
    description: 'Meeting room booking',
  }),
})

const { success, data } = await res.json()
console.log('Booking ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resourceIds: [1],
    datePeriod: {
      from: { timestamp: 1780132384, timezone: 'UTC' },
      to:   { timestamp: 1780135984, timezone: 'UTC' },
    },
    name: 'Meeting room for the demo',
    description: 'Meeting room booking',
  }),
})

const { success, data } = await res.json()

Response fields

The full object of the created booking is returned.

Field Type Description
success boolean Always true on success
data.id number Id of the created booking
data.name string | null Booking name
data.description string | null Booking description
data.resourceIds number[] Ids of the reserved resources
data.datePeriod object Booking period: from and to, each with timestamp and timezone

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 27,
    "name": "Meeting room for the demo",
    "description": "Meeting room booking",
    "resourceIds": [1],
    "datePeriod": {
      "from": { "timestamp": 1780132384, "timezone": "UTC" },
      "to":   { "timestamp": 1780135984, "timezone": "UTC" }
    }
  }
}

Error response example

422 — required fields not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: resourceIds, datePeriod"
  }
}

Errors

HTTP Code Description
422 BITRIX_ERROR Required fields resourceIds and/or datePeriod not passed. Message: Required fields: resourceIds, datePeriod
422 BITRIX_ERROR An empty resourceIds array was passed. Message: Empty resource collection
403 SCOPE_DENIED The API key does not have the booking scope
401 MISSING_API_KEY The X-Api-Key header was not passed
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

See also