لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/workday/schedules-users.md فهرس التوثيق — /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
Parameterid (path) Typeinteger Requiredyes Default— DescriptionWork 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
FielduserId Typeinteger Requiredyes DescriptionEmployee 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
Fieldsuccess Typeboolean Descriptiontrue when the employee is added to the schedule
Fielddata.schedule Typeobject DescriptionThe schedule the employee was added to
Fielddata.schedule.id Typeinteger DescriptionSchedule ID
Fielddata.schedule.name Typestring DescriptionSchedule 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
HTTP400 CodeINVALID_PARAMS Descriptionid or userId is not a positive integer, or the request body is not an object
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo schedule with this id, including a deleted one
HTTP422 CodeBITRIX_ERROR DescriptionThe credential owner lacks permission to manage work schedules — the Bitrix24 text is in message
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime 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
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionAn app key was sent without a session token in Authorization: Bearer
HTTP401 CodeINVALID_SESSION DescriptionThe session token is invalid or has expired
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP429 CodeRATE_LIMITED DescriptionThe 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