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

Replace booking clients

PUT /v1/bookings/:id/clients

Replaces the booking clients with the passed set: clients missing from the request are removed from the booking. An empty clients array removes all clients.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionBooking ID. List: GET /v1/bookings

Request fields (body)

Field Type Required Description
Fieldclients Typearray Requiredyes DescriptionNew set of booking clients. An empty array removes all clients
Fieldclients[].id Typenumber Requiredyes DescriptionCRM contact or company ID. Lists: GET /v1/contacts, GET /v1/companies
Fieldclients[].type.module Typestring Requiredyes DescriptionClient type module: crm. Dictionary: GET /v1/booking-client-types
Fieldclients[].type.code Typestring Requiredyes DescriptionClient type code: CONTACT — contact, COMPANY — company. Dictionary: GET /v1/booking-client-types

The body accepts no other fields: an extra field returns 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/bookings/53/clients" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": [
      { "id": 3013, "type": { "module": "crm", "code": "CONTACT" } },
      { "id": 3149, "type": { "module": "crm", "code": "COMPANY" } }
    ]
  }'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/bookings/53/clients" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": [
      { "id": 3013, "type": { "module": "crm", "code": "CONTACT" } },
      { "id": 3149, "type": { "module": "crm", "code": "COMPANY" } }
    ]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings/53/clients', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    clients: [
      { id: 3013, type: { module: 'crm', code: 'CONTACT' } },
      { id: 3149, type: { module: 'crm', code: 'COMPANY' } },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Booking clients:', data.map((client) => `${client.type.code} ${client.id}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bookings/53/clients', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    clients: [
      { id: 3013, type: { module: 'crm', code: 'CONTACT' } },
      { id: 3149, type: { module: 'crm', code: 'COMPANY' } },
    ],
  }),
})

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

Response fields

The response contains the booking clients, read again after the write.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionBooking clients after the replacement. An empty array if clients was empty
Fielddata[].id Typenumber DescriptionCRM contact or company ID. Get: GET /v1/contacts/:id, GET /v1/companies/:id
Fielddata[].type.code Typestring DescriptionClient type code: CONTACT — contact, COMPANY — company
Fielddata[].type.module Typestring DescriptionClient type module: crm

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3013,
      "type": {
        "code": "CONTACT",
        "module": "crm"
      }
    },
    {
      "id": 3149,
      "type": {
        "code": "COMPANY",
        "module": "crm"
      }
    }
  ]
}

Error response example

400 — the client type is not in the dictionary:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Client type not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionClient type not found — the type.module and type.code pair is not in the client type dictionary. The booking clients stay unchanged
HTTP400 CodeINVALID_PARAMS DescriptionEach client requires id and type.module/type.code — a clients item has no id, type.module or type.code, or its id is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionOnly clients can be written — the body contains a field other than clients
HTTP400 CodeINVALID_PARAMS Descriptionid must be a canonical positive safe integer — the booking id is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionclients must be an array — the body has no clients, or it is not an array
HTTP404 CodeENTITY_NOT_FOUND DescriptionBooking record not found — no booking with this id exists
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo CRM contact or company with the given clients[].id exists. The booking clients stay unchanged
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is rejected before it reaches Bitrix24
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the booking scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded. The effective cap is in the x-ratelimit-limit header
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 did not confirm the booking operation — Bitrix24 did not confirm the write
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 returned an unexpected booking response — Bitrix24 returned a client list of an unexpected shape

Full list of common API errors — Errors.

See also