## Open workday

`POST /v1/workday/open`

Opens a new workday for the current user. For a day in the `OPENED` status, the current state is returned unchanged. A day in the `PAUSED` status is switched back to `OPENED` and tracking resumes. If Bitrix24 leaves the day in the `EXPIRED` status, no new day is opened: Vibecode returns a `409 WORKDAY_EXPIRED` error with instructions for closing the expired day.

## Request fields (body)

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

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `userId` | number | no | Employee identifier. Defaults to the user who owns the key's tokens. Only Bitrix24 account administrators and the employee's direct managers can pass another employee's `userId`. Without those rights Bitrix24 does not return the employee's data |
| `time` | string | no | Start date and time in ISO 8601 format (for example `2026-05-05T09:00:00+02:00`). The date must match the current date. Applied only when the day is in the `CLOSED` status. When this field is set, `report` becomes required |
| `report` | string | no | Reason for the change. Required when `time` is set and for employees on a fixed work schedule |
| `lat` | number | no | Geographic latitude of the workday start point. Returned in the `data.latOpen` field of the response |
| `lon` | number | no | Geographic longitude of the workday start point. Returned in the `data.lonOpen` field of the response |

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/workday/open \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/workday/open \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
  console.log('Opened at:', data.timeStart)
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
}
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` when the opened state is successfully confirmed |
| `data.status` | string | `OPENED` for a successful response. An `EXPIRED` status that has not changed is returned as a 409 error |
| `data.id` | number | Workday record identifier. The same values appear in the [workday history](/docs/workday/records) |
| `data.timeStart` | string | Day start date and time (ISO 8601, employee's time zone) |
| `data.timeFinish` | string \| null | Day finish date and time. `null` for a day that is not closed |
| `data.duration` | string | Day duration in `HH:MM:SS` format. `00:00:00` for a newly opened day |
| `data.timeLeaks` | string | Total duration of pauses for the day in `HH:MM:SS` format |
| `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` if no coordinates were passed |
| `data.lonOpen` | number | Geographic longitude of the start point. `0` if no coordinates were passed |
| `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 |

## 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:00:00",
    "active": true,
    "ipOpen": "",
    "ipClose": "",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 7200
  }
}
```

## Error response example

403 — the key lacks the `timeman` scope:

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

409 — the expired workday is not closed, so no new day is opened:

```json
{
  "success": false,
  "error": {
    "code": "WORKDAY_EXPIRED",
    "message": "The workday remains expired and a new workday was not opened.",
    "hint": "Read workday status for the same user, then close the expired workday with a time on its timeStart date and a report before retrying open."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | The `userId` field is not a positive integer, or Bitrix24 rejected a request field as invalid |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 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 Bitrix24 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 |
| 409 | `WORKDAY_EXPIRED` | The expired day remained `EXPIRED`, so no new day was opened. Get `timeStart` from [current status](/docs/workday/status), close the expired day with `time` on the same date and the required `report`, then retry opening the day |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message`. Possible causes: the `time` date does not match the current date, `report` is missing when `time` is set, the day is already in the required state |
| 429 | `RATE_LIMITED` | The rate limit for requests to Bitrix24 was exceeded |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [Close workday](/docs/workday/close)
- [Pause](/docs/workday/pause)
- [Current status](/docs/workday/status)
- [Workday history](/docs/workday/records)
- [Workday](/docs/workday)