## Open workday

`POST /v1/workday/open`

Opens a new workday for the current user. Vibecode proxies the request to Bitrix24 without additional processing and returns the response as is. Behavior for already active days is determined on the Bitrix24 side: for a day in the `OPENED` status the current state is returned unchanged; for a day in the `PAUSED` status the day is switched back to `OPENED` and tracking resumes.

## Request fields (body)

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

| Field | Type | Req. | Description |
|------|-----|:-----:|---------|
| `userId` | number | no | Employee identifier. Defaults to the user who owns the key's tokens. Other employees' `userId` is available only to Bitrix24 account administrators and the employee's direct managers — otherwise Bitrix24 returns an access error |
| `time` | string | no | Start date and time in ISO 8601 format (for example `2026-05-05T09:00:00+00:00`). The date must match the current one. 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 |
| `lon` | number | no | Geographic longitude of the workday start point |

## 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 { data } = await res.json()
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 { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` on successful opening |
| `data.status` | string | Current status: `OPENED`, `CLOSED`, `PAUSED`, `EXPIRED` |
| `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. For a just-opened day — `00:00:00` |
| `data.timeLeaks` | string | Total duration of pauses for the day in `HH:MM:SS` format |
| `data.active` | boolean | Active workday record flag |
| `data.ipOpen` | string | IP address of the day start. Empty string when opened without IP recording |
| `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. `0` — coordinates were not 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 example `0` corresponds to UTC) |

## Response example

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

## 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` | The `userId` field is not a positive integer, or Bitrix24 rejected a request field validation |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | Invalid API key |
| 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 Bitrix24 portal balance is frozen |
| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request — text is in `message`. Possible causes: the `time` date does not match the current one, `report` is missing when `time` is set, the day is already in the required state |
| 429 | `RATE_LIMITED` | The request limit to Bitrix24 was exceeded |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

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

## See also

- [Close workday](/docs/workday/close) — `POST /v1/workday/close`.
- [Pause](/docs/workday/pause) — `POST /v1/workday/pause`.
- [Current status](/docs/workday/status) — `GET /v1/workday/status`.
- [Workday](/docs/workday) — section overview.