Explain an absence

POST /v1/workday/time-control/reports/:absenceId

Records an explanation for an absence listed in the monthly time-control report: the text, the type and, if needed, an event in the employee's calendar. A repeated call replaces the previous explanation and returns the same response.

Requires the timeman scope. The explanation is recorded on behalf of the credential owner: an employee explains their own absence; an administrator explains any employee's absence by passing that employee's userId. An employee needs access to the monthly report: while time control is switched off (active: false in the time-control settings), they get 403 BITRIX_ACCESS_DENIED. This does not apply to an administrator or a department head. READONLY keys cannot record an explanation.

Parameters

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/workday/time-control/reports/153" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Meeting with a client", "month": 10, "year": 2026, "type": "WORK", "calendar": false}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/workday/time-control/reports/153" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Meeting with a client", "month": 10, "year": 2026, "type": "WORK", "calendar": false}'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/reports/153', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Meeting with a client', month: 10, year: 2026, type: 'WORK', calendar: false }),
})
const { success } = await res.json()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/reports/153', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Meeting with a client', month: 10, year: 2026, type: 'WORK', calendar: false }),
})
const { success } = await res.json()

Response fields

Response example

{
  "success": true,
  "data": true
}

Error response example

404 — no absence with this absenceId in the employee's report for the given month:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Absence not found for this user and month"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

The calendar event is independent of the explanation. With calendar: true the event is created in the employee's personal calendar for the absence interval; its ID is not returned in the response. A repeated explanation neither changes nor deletes the previous event, and with calendar: true it creates another one. To find these events, search the employee's calendar events by the explanation text and the absence time; delete them with DELETE /v1/calendar-events/:id.

See also

• Get the monthly absence report
• List department employees
• Time-control settings
• Calendar events
• Workday