Workday

Employee time tracking: opening and closing the day, pause, current status, Bitrix24 account settings, and work schedule.

Scope: timeman for most operations; records also requires one of user_brief, user_basic, or user | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Which key to choose | Quick start | Full example | Endpoint reference | Error codes

Documentation sections

• Work reports — an employee's report for a period: creating and submitting it, reading subordinates' reports, and marking them
• Daily reports — a report on the workday: reading reports and saving the report text to the workday record
• Endpoints — a switcher for the section's methods with parameters, code examples, and responses
• Time-control settings — reading and updating time-control settings for the entire Bitrix24 account
• Time-control reports — report settings and the monthly absence report
• List department employees — a department's employees for time control
• Explain an absence — an explanation for an absence listed in the monthly time-control report
• Delete a schedule — deleting a work schedule by its identifier
• Schedule members — adding an employee to a work schedule and excluding them from it

Which key to choose

This section works with two key types. The choice determines on whose behalf the workday is recorded.

Actions are recorded on behalf of the key owner (for a personal key) or the session user (for OAuth). For a detailed description of the formats and how to obtain a session_token, see Keys and authorization.

Quick start

1. Check the current status

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

{
  "success": true,
  "data": {
    "status": "CLOSED",
    "id": 1,
    "timeStart": "2026-05-04T09:00:00+02:00",
    "timeFinish": "2026-05-04T18:00:00+02:00",
    "duration": "08:30:00",
    "timeLeaks": "00:30:00",
    "active": true,
    "ipOpen": "203.0.113.10",
    "ipClose": "203.0.113.10",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 7200
  }
}

To read another employee's status, use the same call with the userId parameter:

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

Bitrix24 makes another employee's time sheet available only to Bitrix24 account administrators and to the employee's direct managers. Without those rights Bitrix24 does not return the employee's data. Employee identifiers — GET /v1/users. The workday history of an employee is returned by GET /v1/workday/records, where userId is required and timeman must be combined with user_brief, user_basic, or user.

2. Open the workday

curl -X POST https://vibecode.bitrix24.com/v1/workday/open \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

3. Close the day with a report

curl -X POST https://vibecode.bitrix24.com/v1/workday/close \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "report": "Closed 5 deals, processed 12 leads" }'

Full example: automatic workday tracking

Scenario: a script opens the day at 9:00, tracks the lunch break, and closes the day at 18:00 with an automatic report.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = {
    method,
    headers: { 'X-Api-Key': VIBE_KEY }
  }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Check the current status — so we don't open an already-open day
const { data: current } = await api('GET', '/workday/status')
console.log('Current status:', current.status)

// 2. Open the workday if it is closed
if (current.status === 'CLOSED' || !current.status) {
  const { data: opened } = await api('POST', '/workday/open', {})
  console.log('Day opened at', opened.timeStart)
} else {
  console.log('Day already open since', current.timeStart)
}

// 3. Get the time-tracking settings on the portal
const { data: settings } = await api('GET', '/workday/settings')
console.log('Latest allowed start of day:', settings.ufTmMaxStart)
console.log('Minimum day duration:', settings.ufTmMinDuration)

// 4. Going to lunch — pause the day
const { data: paused } = await api('POST', '/workday/pause', {})
console.log('Status after pause:', paused.status)

// ...break...

// 5. Back from lunch — resume the day
const { data: resumed } = await api('POST', '/workday/open', {})
console.log('Day resumed, status:', resumed.status)

// 6. End of the workday — close it with a report
const { data: closed } = await api('POST', '/workday/close', {
  report: 'Automatic closing'
})
console.log('Day closed, time worked:', closed.duration)
console.log('Break duration:', closed.timeLeaks)

Endpoint reference

An empty successful result is returned as data: null. That is how open, close, pause, status and settings respond when Bitrix24 returns success with no value. There is no service envelope with result, total and next inside data — you do not need to unwrap anything.

The shape of the value itself is preserved: an empty list arrives as an empty array, not as null. That is how schedule behaves — a schedule id that does not exist returns data: [], see Work schedule. So check for emptiness using the shape documented on the method's own page, not with a single comparison to null. The record history (records) is not covered by the rule at all: it has its own paginated payload with meta.

For an interactive method switcher with examples and field tables, see Endpoints.

Error codes

For the full list of common API errors, see Errors.

See also

• Keys and authorization
• Limits and optimization
• Errors