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

"Workday" section endpoints

A switcher for work time tracking methods. Each tab opens the corresponding endpoint page with its parameters, code examples, and real responses.

Bitrix24 API: timeman.* · Scope: timeman

Open workday

POST /v1/workday/open

Opens a new workday for the current user. For a day in the OPENED status, the current state is returned unchanged. A day in the PAUSED status is switched back to OPENED and tracking resumes. If Bitrix24 leaves the day in the EXPIRED status, no new day is opened: Vibecode returns a 409 WORKDAY_EXPIRED error with instructions for closing the expired day.

Request fields (body)

All parameters are optional. The body may be empty: {}.

Field Type Req. Description
userId number no Employee identifier. Defaults to the user who owns the key's tokens. Another employee's userId is available only to Bitrix24 account administrators and the employee's direct managers. Without those rights Bitrix24 does not return the employee's data
time string no Start date and time in ISO 8601 format (for example 2026-05-05T09:00:00+02:00). The date must match the current date. Applied only when the day is in the CLOSED status. When this field is set, report becomes required
report string no Reason for the change. Required when time is set and for employees on a fixed work schedule
lat number no Geographic latitude of the workday start point
lon number no Geographic longitude of the workday start point

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
  console.log('Opened at:', data.timeStart)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
}

Response fields

Field Type Description
success boolean true when the opened state is successfully confirmed
data.status string OPENED for a successful response. An EXPIRED status that has not changed is returned as a 409 error
data.id number Workday record identifier. The same values appear in the workday history
data.timeStart string Day start date and time (ISO 8601, employee's time zone)
data.timeFinish string | null Day finish date and time. null for a day that is not closed
data.duration string Day duration in HH:MM:SS format. For a just-opened day — 00:00:00
data.timeLeaks string Total duration of pauses for the day in HH:MM:SS format
data.active boolean Whether the workday record is active
data.ipOpen string IP address of the day start. Empty string if the day was started without recording an IP
data.ipClose string IP address of the day finish. Empty string for a day that is not closed
data.latOpen number Geographic latitude of the start point. 0 — coordinates were not passed
data.lonOpen number Geographic longitude of the start point. 0 — coordinates were not passed
data.latClose number Geographic latitude of the finish point
data.lonClose number Geographic longitude of the finish point
data.tzOffset number Employee's time zone offset in seconds. Depends on the employee's settings in the Bitrix24 account. The value 7200 corresponds to UTC+2

Response example

JSON 
{
  "success": true,
  "data": {
    "status": "OPENED",
    "id": 1,
    "timeStart": "2026-05-05T09:00:00+02:00",
    "timeFinish": null,
    "duration": "00:00:00",
    "timeLeaks": "00:00:00",
    "active": true,
    "ipOpen": "",
    "ipClose": "",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 7200
  }
}

Error response example

403 — the key lacks the timeman scope:

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

409 — the expired workday is not closed, so no new day is opened:

JSON 
{
  "success": false,
  "error": {
    "code": "WORKDAY_EXPIRED",
    "message": "The workday remains expired and a new workday was not opened.",
    "hint": "Read workday status for the same user, then close the expired workday with a time on its timeStart date and a report before retrying open."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS The userId field is not a positive integer, or Bitrix24 rejected a request field as invalid
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 KEY_EXPIRED The API key has expired
401 TOKEN_MISSING The key has no OAuth tokens configured for the Bitrix24 portal
402 ACCOUNT_FROZEN The portal balance is frozen
403 SCOPE_DENIED The key lacks the timeman scope
409 WORKDAY_EXPIRED The expired day remained EXPIRED, so no new day was opened. Get timeStart from current status, close the expired day with time on the same date and the required report, then retry open
422 BITRIX_ERROR Bitrix24 rejected the request — text is in message. Possible causes: the time date does not match the current date, report is missing when time is set, the day is already in the required state
429 RATE_LIMITED The rate limit for requests to Bitrix24 was exceeded
502 BITRIX_UNAVAILABLE The Bitrix24 portal is unavailable

The full list of common API errors — Errors.

See also