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 accepts a report for the day and a finish point.

Request fields (body)

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

Field Type Required Description
FielduserId Typenumber Requiredno DescriptionEmployee 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
Fieldtime Typestring Requiredno DescriptionFinish date and time in ISO 8601 format (for example 2026-05-05T18:00:00+02: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
Fieldreport Typestring Requiredno DescriptionFinal report for the day. Required when time is set and for employees on a fixed work schedule
Fieldlat Typenumber Requiredno DescriptionGeographic latitude of the finish point. Returned in the data.latClose field of the response
Fieldlon Typenumber Requiredno DescriptionGeographic longitude of the finish point. Returned in the data.lonClose field of the response

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
Fieldsuccess Typeboolean Descriptiontrue on a successful close
Fielddata.status Typestring DescriptionStatus after closing — CLOSED
Fielddata.id Typenumber DescriptionWorkday record identifier. The same values appear in the workday history
Fielddata.timeStart Typestring DescriptionDay start date and time (ISO 8601)
Fielddata.timeFinish Typestring DescriptionDay finish date and time (ISO 8601)
Fielddata.duration Typestring DescriptionDay duration in HH:MM:SS format, excluding pauses
Fielddata.timeLeaks Typestring DescriptionTotal duration of pauses for the day in HH:MM:SS format
Fielddata.active Typeboolean DescriptionWhether the workday record is active
Fielddata.ipOpen Typestring DescriptionIP address of the day start
Fielddata.ipClose Typestring DescriptionIP address of the day finish
Fielddata.latOpen Typenumber DescriptionGeographic latitude of the start point. 0 — coordinates were not passed
Fielddata.lonOpen Typenumber DescriptionGeographic longitude of the start point
Fielddata.latClose Typenumber DescriptionGeographic latitude of the finish point
Fielddata.lonClose Typenumber DescriptionGeographic longitude of the finish point
Fielddata.tzOffset Typenumber DescriptionEmployee'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": "CLOSED",
    "id": 1,
    "timeStart": "2026-05-05T09:00:00+02:00",
    "timeFinish": "2026-05-05T18: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
  }
}

Error response example

422 — an attempt to close an already closed day:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe userId field is not a positive integer, or Bitrix24 rejected a request field as invalid
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 returns this error
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request — the 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
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

  • 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 time unaccounted for.

See also