For AI agents: markdown of this page — /docs-content-en/workday/schedules-users.md documentation index — /llms.txt

Add an employee to a schedule

POST /v1/workday/schedules/:id/users

Adds an employee to a work schedule. If the employee was excluded from this schedule, the exclusion is lifted and the schedule applies to them again.

Requires the timeman scope and permission to manage work schedules in Bitrix24: the Bitrix24 account administrator always has it; an employee is granted it in the Time Management access permission settings. READONLY keys cannot add an employee to a schedule. To exclude an employee from a schedule, see Remove an employee from a schedule.

Parameters

Parameter Type Required Default Description
id (path) integer yes — Work schedule ID, a positive integer. Where to get it: the work schedules page of the Bitrix24 account (/timeman/schedules/); the API has no schedule list. Check by ID: GET /v1/workday/schedule

Request fields (body)

Field Type Required Description
userId integer yes Employee ID, a positive integer. List: GET /v1/users

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workday/schedules/13/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": 503}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/workday/schedules/13/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": 503}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/schedules/13/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 503 }),
})
const { data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/schedules/13/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 503 }),
})
const { data } = await res.json()

Response fields

Field Type Description
success boolean true when the employee is added to the schedule
data.schedule object The schedule the employee was added to
data.schedule.id integer Schedule ID
data.schedule.name string Schedule name

Response example

JSON 
{
  "success": true,
  "data": {
    "schedule": {
      "id": 13,
      "name": "Office 5/2"
    }
  }
}

Error response example

404 — no schedule with this id, or it has been deleted:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Schedule was not found"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS id or userId is not a positive integer, or the request body is not an object
404 ENTITY_NOT_FOUND No schedule with this id, including a deleted one
422 BITRIX_ERROR The credential owner lacks permission to manage work schedules — the Bitrix24 text is in message
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
409 TIMEMAN_MODULE_NOT_ENABLED Time Management is not available on this portal: the Time Management tool is switched off in the portal settings, or the module is not included in the plan
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a response of an unexpected shape
401 MISSING_API_KEY The X-Api-Key header was not passed
401 TOKEN_MISSING An app key was sent without a session token in Authorization: Bearer
401 INVALID_SESSION The session token is invalid or has expired
403 SCOPE_DENIED The key lacks the timeman scope
429 RATE_LIMITED The general request limit was exceeded; the retry delay is in the Retry-After header

The full list of common API errors — Errors.

Known specifics

The employee's other schedules stay unchanged. Adding an employee to a schedule does not move them out of their other schedules: those assignments remain. To have the employee work only on the new schedule, exclude them from the previous one with DELETE /v1/workday/schedules/:id/users/:userId.

The employee is not checked for existence. An assignment is created even with a nonexistent userId: the response is 200, and the schedule gets an assignment for that ID. To avoid adding a nonexistent employee to a schedule, look up their ID first with GET /v1/users.

See also