> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The User Offboarding object

> Start or schedule an offboarding for one identity, follow its status, and cancel it before it finishes.

A user offboarding runs your organization's offboarding workflow for one identity, either now or at
a time you schedule. With v1 you can start one, read it, and cancel it. No endpoint lists
offboardings, so store the `id` that
[Create User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/create-user-offboarding.md) returns.

```json The User Offboarding object theme={null}
{
  "id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
  "user_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
  "status": "scheduled",
  "scheduled_at": "2026-10-01T17:00:00Z",
  "created_at": "2026-09-25T20:14:03.518204Z",
  "cancelled_at": null,
  "completed_at": null
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the offboarding. Always present. |
| `user_id` | string | The identity being offboarded, given as the `id` of a [user](https://docs.lumos.com/reference/v1/objects/user.md). Always present. |
| `status` | string | Where the offboarding stands. See [Statuses](#statuses). Always present. |
| `scheduled_at` | string or null | When the offboarding is scheduled to run. `null` for one that ran immediately. |
| `created_at` | string or null | When the offboarding was created. |
| `cancelled_at` | string or null | When the offboarding was cancelled, if it was. |
| `completed_at` | string or null | When the offboarding completed, if it has. |
| `workflow_config_id` | string or null | The offboarding workflow configuration that the offboarding runs under. Returned only for organizations with the multiple offboarding workflows feature. See [Offboarding workflow configurations](#offboarding-workflow-configurations). |

All timestamps are UTC.

## Statuses

| Status | Meaning |
| - | - |
| `scheduled` | The offboarding is waiting for `scheduled_at`. |
| `in-progress` | The offboarding workflow is running, including while it waits for someone to complete a task. |
| `diverted` | Lumos paused your organization's offboardings because an unusually high number started in a short time, and notified your admins. Contact your Lumos representative to resume or cancel the offboarding. |
| `cancelled` | Someone cancelled the offboarding. |
| `failed` | A step in the offboarding workflow failed, and the offboarding stopped. |
| `expired` | A task in the offboarding workflow expired before anyone completed it, so the remaining steps didn't run. |
| `completed` | The offboarding workflow finished, or an admin marked the offboarding complete. |

## Starting an offboarding

[Create User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/create-user-offboarding.md) takes
the identity's `user_id` and returns the offboarding with `201`. This request body schedules one:

```json theme={null}
{ "user_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "scheduled_at": "2026-10-01T17:00:00Z" }
```

Omit `scheduled_at` to start the offboarding now. To schedule it, send a future ISO 8601
date-time. Lumos converts a value with a time zone to UTC, and reads a value without a time zone as
UTC.

| Response | When |
| - | - |
| `400` | `scheduled_at` is in the past. |
| `400` | The identity didn't come from one of your organization's sources of truth, or has no email address. |
| `404` | No identity with that `user_id` exists in your organization. |
| `409` | An offboarding for this identity is already scheduled or in progress. |

## Offboarding workflow configurations

`workflow_config_id` names an offboarding workflow configuration, which you create in Lumos. It
isn't a [workflow](https://docs.lumos.com/reference/v1/objects/workflow.md) from `/v1/workflows`, and no v1 endpoint lists
configurations.

Omit `workflow_config_id` to use the configuration that your organization selected for automatic
offboarding. A `workflow_config_id` that Lumos can't find returns `404`.

If your organization doesn't have the multiple offboarding workflows feature, sending
`workflow_config_id` returns `400`. The response is the same as for an unknown field, as
[Field-level errors](https://docs.lumos.com/reference/v1/errors.md#field-level-errors) describes.

## Cancelling

[Cancel User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/cancel-user-offboarding.md) stops an
offboarding whose status is `scheduled` or `in-progress`, and returns `204`. In any other status the
call returns `409`.

## Who can do what

Of the built-in roles, Admin can start and cancel offboardings, and Admin and Read Only Admin can
read them. A custom role can also allow these actions. Any other role gets `403`.

## Endpoints

| Endpoint | Path |
| - | - |
| [Create User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/create-user-offboarding.md) | `POST /v1/lifecycle-management/user-offboardings` |
| [Get User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/get-user-offboarding.md) | `GET /v1/lifecycle-management/user-offboardings/{user_offboarding_id}` |
| [Cancel User Offboarding](https://docs.lumos.com/api-reference/v1/lifecycle-management/cancel-user-offboarding.md) | `POST /v1/lifecycle-management/user-offboardings/{user_offboarding_id}:cancel` |