## Current status

`GET /v1/workday/status`

Returns the current state of an employee's workday: status, start and finish time, duration, pauses.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|--------------|---------|
| `userId` | number | no | Employee 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 |

## Examples

### curl — personal key

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

### curl — another employee's status

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/workday/status?userId=503"
```

### curl — OAuth application

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

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/status', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Status:', data.status)
console.log('Active day:', data.active)
console.log('Duration:', data.duration)
```

### JavaScript — another employee's status

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/status?userId=503', {
  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/status', {
  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` on a successful response |
| `data.status` | string | Day status: `OPENED`, `CLOSED`, `PAUSED`, `EXPIRED` |
| `data.id` | number | Workday record identifier. The same values appear in the [workday history](/docs/workday/records) |
| `data.timeStart` | string | Date and time the current or last day started (ISO 8601) |
| `data.timeFinish` | string \| null | Date and time the day finished. `null` until the day is closed, including while it is paused |
| `data.duration` | string | Day duration in `HH:MM:SS` format, excluding pauses. `00:00:00` until the day is closed |
| `data.timeLeaks` | string | Total duration of pauses for the day in `HH:MM:SS` format. The current pause is added to the total once the day is resumed or closed |
| `data.active` | boolean | Whether the workday record is active |
| `data.ipOpen` | string | IP address of the day start. Empty string if the day was started without recording an IP |
| `data.ipClose` | string | IP address of the day finish. Empty string for a day that is not closed |
| `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 value `7200` corresponds to UTC+2 |

When the requested employee has no workday record, `data` contains only `status` — the remaining fields are absent. See "Degenerate response without a day record" in "Known specifics".

## Possible `status` values

| Status | Description |
|--------|---------|
| `OPENED` | Workday is open |
| `CLOSED` | Workday is closed |
| `PAUSED` | Workday is paused |
| `EXPIRED` | Workday was not closed before the start of the next calendar day |

## Response example

```json
{
  "success": true,
  "data": {
    "status": "OPENED",
    "id": 1,
    "timeStart": "2026-05-05T09:00:00+02:00",
    "timeFinish": null,
    "duration": "00:00:00",
    "timeLeaks": "00:30:00",
    "active": true,
    "ipOpen": "203.0.113.10",
    "ipClose": "",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 7200
  }
}
```

For an employee with no workday record, the response degenerates to a single `status` field:

```json
{
  "success": true,
  "data": {
    "status": "CLOSED"
  }
}
```

## 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 |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `userId` is not a positive integer |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |
| 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 |
| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Time 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 answers the same way |
| 422 | `BITRIX_ERROR` | Other Bitrix24 errors — the text is in `message` |
| 429 | `RATE_LIMITED` | The rate limit for requests to Bitrix24 was exceeded |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

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

## Known specifics

- **State after closing.** After the day is closed, the endpoint keeps returning the last day's data (`CLOSED`, with `timeFinish` filled in) until the next one is opened — the report on a closed day is available through the same request.
- **The record may be of any age — compare `timeStart` with today's date.** `status` and `timeStart` describe the employee's *last* workday record, and it may be arbitrarily old: Bitrix24 `timeman.status` returns the last record regardless of its age. Both a day `CLOSED` three years ago and a day left `EXPIRED` (opened and not closed) five days ago are returned as is — neither of them means "today". The endpoint has no "today only" filter, so to tell whether the day belongs to the current date, compare the date from `timeStart` with today's date on your side before trusting `status`. For a team dashboard, treat a record whose `timeStart` is not today as "the workday has not been started today".
- **Degenerate response without a day record.** If the requested employee has no workday record, `data` contains only the `status` field. The remaining fields (`timeStart`, `timeFinish`, `duration` and others) are absent from the response, so check that a field is present before reading it. The record is missing, for example, for an employee whose day has never been opened.
- **Closing an expired day.** A day in the `EXPIRED` status is closed retroactively. In [`POST /v1/workday/close`](/docs/workday/close), pass the `time` parameter with a date equal to the day's open date — that is the `timeStart` value from this endpoint's response — together with the mandatory `report`. A `time` date that differs from the open date returns `422`.

## See also

- [Open workday](/docs/workday/open)
- [Close workday](/docs/workday/close)
- [Pause](/docs/workday/pause)
- [Tracking settings](/docs/workday/settings)
- [Workday history](/docs/workday/records)
- [Workday](/docs/workday)