## Get time-control report settings

`GET /v1/workday/time-control/report-settings`

Returns the credential owner's access to monthly time-control reports: their ID, role, and the departments whose reports are available to them. Call it before requesting a monthly report to find out your own ID and which employees you can access.

Requires the `timeman` scope. The method is available to any employee of the Bitrix24 account and describes the permissions of the user whose credentials were used for the request: for a personal key, that is the key owner; for an app key, the user whose session token is passed in `Authorization`. READONLY keys can read the report settings. Time-control settings for the whole Bitrix24 account are described on the [Get time-control settings](/docs/workday/time-control-settings-list) page.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/workday/time-control/report-settings" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/workday/time-control/report-settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/report-settings', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/time-control/report-settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` when the request succeeds |
| `data` | object | The credential owner's access to monthly reports |
| `data.active` | boolean | Whether time control is switched on in the Bitrix24 account. To change it: [Update time-control settings](/docs/workday/time-control-settings-update) |
| `data.userId` | integer | Credential owner's ID. Can be used as `userId` in the [monthly absence report](/docs/workday/time-control-reports) when an employee requests their own report |
| `data.userAdmin` | boolean | Whether the credential owner is an administrator |
| `data.userHead` | boolean | Whether the credential owner heads at least one department |
| `data.departments` | array | Departments whose reports are available to the credential owner: all departments of the Bitrix24 account for an administrator, the departments they head for a department head, an empty array for other employees |
| `data.departments[].id` | string | Department ID. Can be used as `departmentId` in the [list of department employees](/docs/workday/time-control-users) |
| `data.departments[].name` | string | Department name |
| `data.minimumIdleForReport` | integer | Minimum absence, in minutes, for which an employee is asked for an explanation |
| `data.reportViewType` | string | Which monthly reports the credential owner sees: `simple` — only their own, `head` — reports of employees in their departments, `full` — reports of all employees, `none` — reports are not available |

## Response example

Response to the head of one department:

```json
{
  "success": true,
  "data": {
    "active": true,
    "userId": 547,
    "userAdmin": false,
    "userHead": true,
    "departments": [
      {
        "id": "9",
        "name": "Marketing and Advertising"
      }
    ],
    "minimumIdleForReport": 15,
    "reportViewType": "head"
  }
}
```

## Error response example

403 — the key lacks the `timeman` scope:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 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 |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `TOKEN_MISSING` | An app key was sent without a session token in `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | The session token is invalid or has expired |
| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |
| 429 | `RATE_LIMITED` | The general request limit was exceeded; the retry delay is in the `Retry-After` header |

The full list of common API errors — [Errors](/docs/errors).

## See also

- [Get the monthly absence report](/docs/workday/time-control-reports)
- [List department employees](/docs/workday/time-control-users)
- [Explain an absence](/docs/workday/time-control-explain)
- [Time-control settings](/docs/workday/time-control-settings)
- [Workday](/docs/workday)