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

Close workday

POST /v1/workday/close

Finishes the current workday and records its duration. The call supports a report for the day and a finish point.

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. Other employees' userId is available only to Bitrix24 account administrators and the employee's direct managers — otherwise Bitrix24 returns an access error
time string no Finish date and time in ISO 8601 format (for example 2026-05-05T18:00:00+00:00). The date must match the day's start date — the timeStart value from GET /v1/workday/status. When this field is set, report becomes required
report string no Final report for the day. Required when time is set and for employees on a fixed work schedule
lat number no Geographic latitude of the finish point
lon number no Geographic longitude of the finish point

Examples

curl — personal key

Terminal 
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" }'

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/close', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    report: 'Closed 5 deals, processed 12 leads',
  }),
})
const { data } = await res.json()
console.log('Day duration:', data.duration)
console.log('Breaks:', data.timeLeaks)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/close', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    report: 'Closed 5 deals, processed 12 leads',
  }),
})
const { data } = await res.json()

Response fields

Field Type Description
success boolean true on successful closing
data.status string Status after closing — CLOSED
data.timeStart string Day start date and time (ISO 8601)
data.timeFinish string Day finish date and time (ISO 8601)
data.duration string Day duration in HH:MM:SS format, excluding pauses
data.timeLeaks string Total duration of pauses for the day in HH:MM:SS format
data.active boolean Active workday record flag
data.ipOpen string IP address of the day start
data.ipClose string IP address of the day finish
data.latOpen number Geographic latitude of the start point. 0 — coordinates were not passed
data.lonOpen number Geographic longitude of the start point
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 example 0 corresponds to UTC)

Response example

JSON 
{
  "success": true,
  "data": {
    "status": "CLOSED",
    "timeStart": "2026-05-05T09:00:00+00:00",
    "timeFinish": "2026-05-05T18:00:00+00:00",
    "duration": "08:00: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": 0
  }
}

Error response example

422 — an attempt to close an already closed day:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Cannot perform the action"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS The userId field is not a positive integer, or Bitrix24 rejected a request field validation
401 MISSING_API_KEY The X-Api-Key header was not passed
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 portal
402 ACCOUNT_FROZEN The portal balance is frozen
403 SCOPE_DENIED The key lacks the timeman scope
422 BITRIX_ERROR Bitrix24 rejected the request — text is in message. Possible causes: the day is already closed, the time date does not match the day's start date, report is missing when time is set
429 RATE_LIMITED The request limit to Bitrix24 was exceeded
502 BITRIX_UNAVAILABLE The Bitrix24 portal is unavailable

The full list of common API errors — Errors.

Known specifics

  • Closing while paused. If the day is in the PAUSED status, the call closes the day, recording timeFinish at the moment of closing. The duration of pauses is included in timeLeaks.
  • The sum of duration and timeLeaks equals the difference between timeFinish and timeStart — that is, the total time since the day was opened is split into worked time and breaks with no loss.

See also