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

Tracking settings

GET /v1/workday/settings

Returns the work time tracking settings that apply to the current user or to the specified employee in the Bitrix24 account: whether work time tracking is enabled, whether the schedule is flexible, the permitted day start and finish times, and the minimum duration.

Parameters

Parameter Type Required Description
ParameteruserId Typenumber Requiredno DescriptionEmployee identifier. Defaults to the user who owns the key's tokens. Bitrix24 returns another employee's settings only to a user with the right to manage work time of all employees. Without that right the request is rejected with 422 BITRIX_ERROR

Examples

curl — personal key

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/workday/settings

curl — another employee's settings

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/workday/settings?userId=503"

curl — OAuth application

Terminal 
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/workday/settings

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Time tracking enabled:', data.ufTimeman)
console.log('Flexible schedule:', data.ufTmFree)
console.log('Latest permitted start:', data.ufTmMaxStart)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful response
Fielddata.ufTimeman Typeboolean DescriptionWhether work time tracking is enabled for the user
Fielddata.ufTmFree Typeboolean DescriptionFlexible schedule. true — no restrictions on the day start and finish; false — the ufTmMaxStart/ufTmMinFinish/ufTmMinDuration fields apply
Fielddata.ufTmMaxStart Typestring DescriptionThe latest permitted day start time in HH:MM:SS format
Fielddata.ufTmMinFinish Typestring DescriptionThe earliest permitted day finish time in HH:MM:SS format
Fielddata.ufTmMinDuration Typestring DescriptionThe minimum workday duration in HH:MM:SS format
Fielddata.ufTmAllowedDelta Typestring DescriptionThe permitted deviation from the configured start and finish times in HH:MM:SS format
Fielddata.admin Typeboolean DescriptionWhether the user is a work time tracking administrator. Returned only in the caller's own settings, absent for another employee

Response example

JSON 
{
  "success": true,
  "data": {
    "ufTimeman": true,
    "ufTmFree": true,
    "ufTmMaxStart": "09:15:00",
    "ufTmMinFinish": "17:45:00",
    "ufTmMinDuration": "08:00:00",
    "ufTmAllowedDelta": "00:15:00",
    "admin": true
  }
}

Error response example

403 — the key lacks the timeman scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'timeman' scope"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no OAuth tokens configured for the portal
HTTP402 CodeACCOUNT_FROZEN DescriptionThe portal balance is frozen
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal: the module is not installed (not included in the plan), or the tool is switched off in portal settings. Ask a portal administrator to enable it — until then every timeman.* method answers the same way
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request — text is in message
HTTP429 CodeRATE_LIMITED DescriptionThe rate limit for requests to Bitrix24 was exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable

The full list of common API errors — Errors.

Known specifics

  • Tied to the key's tokens. Without userId the response corresponds to the user who owns the key's tokens. Values may differ across employees if they have different work schedules configured.
  • Per-employee tracking flag. To find out whether work time is tracked for a specific employee, pass their userId and read data.ufTimeman. A manager's right over their own subordinates is not enough: Bitrix24 requires the right over the work time of all employees.

See also