## Remove an employee from a schedule

`DELETE /v1/workday/schedules/:id/users/:userId`

Excludes an employee from a work schedule, including a schedule assigned to all employees, and removes their future shifts on this schedule. To bring the employee back to the schedule, add them again.

Requires the `timeman` scope and permission to manage work schedules in Bitrix24: the Bitrix24 account administrator always has it; an employee is granted it in the Time Management access permission settings. READONLY keys cannot exclude an employee from a schedule. To add an employee to a schedule, see [Add an employee to a schedule](/docs/workday/schedules-users).

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `id` (path) | integer | yes | — | Work schedule ID, a positive integer. Where to get it: the work schedules page of the Bitrix24 account (`/timeman/schedules/`); the API has no schedule list. Check by ID: [`GET /v1/workday/schedule`](/docs/workday/schedule) |
| `userId` (path) | integer | yes | — | Employee ID, a positive integer. List: [`GET /v1/users`](/docs/entities/users/list) |

## Examples

### curl — personal key

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/workday/schedules/13/users/503" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/workday/schedules/13/users/503" \
  -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/schedules/13/users/503', {
  method: 'DELETE',
  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/schedules/13/users/503', {
  method: 'DELETE',
  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 employee is excluded from the schedule |
| `data.schedule` | object | The schedule the employee was excluded from |
| `data.schedule.id` | integer | Schedule ID |
| `data.schedule.name` | string | Schedule name |

## Response example

```json
{
  "success": true,
  "data": {
    "schedule": {
      "id": 13,
      "name": "Office 5/2"
    }
  }
}
```

## Error response example

404 — no schedule with this `id`, or it has been deleted:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Schedule was not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `id` or `userId` is not a positive integer |
| 404 | `ENTITY_NOT_FOUND` | No schedule with this `id`, including after deletion |
| 422 | `BITRIX_ERROR` | The credential owner lacks permission to manage work schedules — the Bitrix24 text is in `message` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 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).

## Known specifics

**Exclusion does not delete the schedule assignment.** The employee remains among the assigned employees but is marked as excluded, so the schedule does not apply to them. [`POST /v1/workday/schedules/:id/users`](/docs/workday/schedules-users) removes the mark.

**The employee's other schedules stay unchanged.** The exclusion applies only to the schedule identified by `id`.

## See also

- [Add an employee to a schedule](/docs/workday/schedules-users)
- [Work schedule](/docs/workday/schedule)
- [Delete a schedule](/docs/workday/schedules-delete)
- [Workday](/docs/workday)