[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-workday\u002Ftime-control-explain":3,"docs-tabs-workday\u002Ftime-control-explain":6},{"content":4,"lastmod":5},"## Explain an absence\n\n`POST \u002Fv1\u002Fworkday\u002Ftime-control\u002Freports\u002F:absenceId`\n\nRecords 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.\n\nRequires 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](\u002Fdocs\u002Fworkday\u002Ftime-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.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `absenceId` (path) | integer | yes | — | Absence ID — `report.days[].reports[].id` from the `\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports` response on the [Get the monthly absence report](\u002Fdocs\u002Fworkday\u002Ftime-control-reports) page |\n\n## Request fields (body)\n\n| Field | Type | Required | Default | Description |\n|------|-----|:-----:|-----------|----------|\n| `text` | string | yes | — | Explanation text; must not be empty |\n| `month` | integer | yes | — | Month of the absence, from 1 to 12. The absence is looked up in the employee's monthly report by month and year |\n| `year` | integer | yes | — | Year of the absence, from 1900 to 3000 |\n| `type` | string | no | `PRIVATE` | Explanation type: `WORK` — work-related, `PRIVATE` — personal |\n| `calendar` | boolean | no | `true` | Create an event in the employee's calendar for the duration of the absence, with the explanation text. With `type: PRIVATE` the event is private |\n| `userId` | integer | no | credential owner | ID of the employee whose absence is explained. Honored only for an administrator, ignored for everyone else. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist), department employees — [`GET \u002Fv1\u002Fworkday\u002Ftime-control\u002Fusers`](\u002Fdocs\u002Fworkday\u002Ftime-control-users) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports\u002F153\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"text\": \"Meeting with a client\", \"month\": 10, \"year\": 2026, \"type\": \"WORK\", \"calendar\": false}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports\u002F153\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"text\": \"Meeting with a client\", \"month\": 10, \"year\": 2026, \"type\": \"WORK\", \"calendar\": false}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports\u002F153', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ text: 'Meeting with a client', month: 10, year: 2026, type: 'WORK', calendar: false }),\n})\nconst { success } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fworkday\u002Ftime-control\u002Freports\u002F153', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ text: 'Meeting with a client', month: 10, year: 2026, type: 'WORK', calendar: false }),\n})\nconst { success } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when the explanation is recorded |\n| `data` | boolean | Always `true`. The recorded explanation is visible in the `reportType` and `reportText` fields of the absence in the [monthly report](\u002Fdocs\u002Fworkday\u002Ftime-control-reports) |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": true\n}\n```\n\n## Error response example\n\n404 — no absence with this `absenceId` in the employee's report for the given month:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Absence not found for this user and month\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `absenceId` is not a positive integer, `text` is empty, `type` is neither `WORK` nor `PRIVATE`, `calendar` is not a boolean, `month` or `year` is missing or out of range, `userId` is not a positive integer, or the request body is not an object |\n| 404 | `ENTITY_NOT_FOUND` | No absence with this `absenceId` in the employee's report for the given month: another month, someone else's absence, or a nonexistent `userId` passed by an administrator |\n| 403 | `BITRIX_ACCESS_DENIED` | The employee has no access to the monthly report: time control is switched off (`active: false` in the [time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings)). A disabled Time Management tool on the portal returns 409, not this code |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Time Management is not available on this portal: the Time Management tool is switched off in the portal settings, or the module is not included in the plan |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | An app key was sent without a session token in `Authorization: Bearer` |\n| 401 | `INVALID_SESSION` | The session token is invalid or has expired |\n| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |\n| 429 | `RATE_LIMITED` | The general request limit was exceeded; the retry delay is in the `Retry-After` header |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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](\u002Fdocs\u002Fentities\u002Fcalendar-events) by the explanation text and the absence time; delete them with [`DELETE \u002Fv1\u002Fcalendar-events\u002F:id`](\u002Fdocs\u002Fentities\u002Fcalendar-events\u002Fdelete).\n\n## See also\n\n- [Get the monthly absence report](\u002Fdocs\u002Fworkday\u002Ftime-control-reports)\n- [List department employees](\u002Fdocs\u002Fworkday\u002Ftime-control-users)\n- [Time-control settings](\u002Fdocs\u002Fworkday\u002Ftime-control-settings)\n- [Calendar events](\u002Fdocs\u002Fentities\u002Fcalendar-events)\n- [Workday](\u002Fdocs\u002Fworkday)\n","2026-10-12",{},1795000592552]