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

# Offboard Workers

> Schedule offboarding, cancel pending offboarding, and reinstate former workers

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

Offboarding moves a worker from **Active** to **Former** status on a scheduled exit date. Use it when an employee resigns, a contract ends, or you need to remove someone from your active workforce. Cadana handles the status transition automatically on the exit date — you just schedule it.

***

## Schedule Offboarding

To schedule a worker for offboarding, provide an exit date and reason. You can optionally adjust their compensation for the exit period.

<Tabs>
  <Tab title="With Compensation">
    <ApiExample method="POST" path="/v1/persons/{personId}/offboard" body={{ exitDate: "2025-06-30", reason: "Voluntary resignation", compensation: { type: "salaried", salary: { amount: 600000, currency: "USD" }, frequency: "monthly" }, includeInRegularPayroll: true }} reference="/api-reference/workforce/persons/schedule-offboarding" />
  </Tab>

  <Tab title="Without Compensation">
    <ApiExample method="POST" path="/v1/persons/{personId}/offboard" body={{ exitDate: "2025-06-30", reason: "End of contract" }} reference="/api-reference/workforce/persons/schedule-offboarding" />
  </Tab>
</Tabs>

### Request Fields

| Field                     | Type            | Required | Description                                                                                                                                                                                                |
| :------------------------ | :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exitDate`                | `string` (date) | Yes      | The date the person will exit the organization (`YYYY-MM-DD`)                                                                                                                                              |
| `reason`                  | `string`        | Yes      | The reason for offboarding                                                                                                                                                                                 |
| `compensation`            | `object`        | No       | Adjusted compensation for the exit period (uses the same `compInfo` schema as onboarding). Omit to keep current compensation unchanged. If provided, proration for partial periods is your responsibility. |
| `includeInRegularPayroll` | `boolean`       | No       | Whether to include the person in the regular payroll run for their exit period                                                                                                                             |

<Warning>
  If you set `includeInRegularPayroll` to `true`, the exit date must fall after the business's payroll cutoff day for the current period. Otherwise, the person may not be included in the expected payroll run. The payroll cutoff day is configured in the Dashboard under **Settings → Company Profile → Payroll & Tax Info**.
</Warning>

***

## Cancel Offboarding

Cancel a pending offboarding if the decision is reversed or it was scheduled in error. This returns the person to **Active** status.

<ApiExample method="POST" path="/v1/persons/{personId}/cancelOffboarding" reference="/api-reference/workforce/persons/cancel-offboarding" />

<Note>
  The person must be in **Offboarding** status. Cancelling offboarding for a person who is already **Former** or **Active** returns a `400` error.
</Note>

***

## Reinstate a Worker

To bring a former worker back to active status — for example, a rehire or a reversal — use the reinstate endpoint.

<ApiExample method="POST" path="/v1/persons/{personId}/reinstate" reference="/api-reference/workforce/persons/reinstate" />

<Note>
  The person must be in **Former** status. Reinstating a person who is still **Active** or **Offboarding** returns a `400` error.
</Note>

***

## Offboarding Lifecycle

The diagram below shows how a person's status transitions through the offboarding process.

```mermaid theme={null}
stateDiagram-v2
    Active --> Offboarding: Schedule offboarding
    Offboarding --> Active: Cancel offboarding
    Offboarding --> Former: Auto-completes day after exit date
    Former --> Active: Reinstate
```

<Info>
  Offboarding completes automatically on the day after the exit date. For example, if the exit date is June 30, the person's status changes to **Former** on July 1.
</Info>

***

## Webhook Events

Cadana delivers webhook events for each offboarding lifecycle transition. Subscribe to these via the [Webhooks](/reference/webhooks) configuration.

| Event                          | Fired when                            | Payload              |
| :----------------------------- | :------------------------------------ | :------------------- |
| `person.offboarding.scheduled` | Offboarding is scheduled              | `exitDate`, `reason` |
| `person.offboarding.cancelled` | Pending offboarding is cancelled      | Person ID only       |
| `person.offboarding.completed` | Person transitions to Former          | `exitDate`, `reason` |
| `person.reinstated`            | Former person is reinstated to Active | Person ID only       |

<Tip>
  To get full offboarding details (compensation, payroll inclusion), query [`GET /v1/persons/{personId}`](/api-reference/workforce/persons/get) after receiving the event.
</Tip>

See [Events](/reference/events#offboarding) for full payload examples.

## Notifications

When offboarding is scheduled, Cadana sends an **offboarding scheduled** email notification to the person, informing them of their exit date.

***

## Offboarding Details in GET Response

While a person is in **Offboarding** status, the [`GET /v1/persons/{personId}`](/api-reference/workforce/persons/get) response includes an `offboardingDetails` object with the scheduled offboarding information.

| Field                     | Type            | Description                                               |
| :------------------------ | :-------------- | :-------------------------------------------------------- |
| `exitDate`                | `string` (date) | The scheduled exit date                                   |
| `reason`                  | `string`        | The reason for offboarding                                |
| `compensation`            | `object`        | Adjusted compensation for the exit period, if provided    |
| `includeInRegularPayroll` | `boolean`       | Whether the person is included in the regular payroll run |

<Note>
  The `offboardingDetails` field is only present while the person is in **Offboarding** status. Once they transition to **Former** or are cancelled back to **Active**, this field is no longer included in the response.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Payroll Lifecycle" icon="arrows-spin" href="/workforce/payroll-lifecycle">
    Understand payroll status transitions and webhook events
  </Card>

  <Card title="Pay Workers via Payroll" icon="rocket" href="/workforce/pay-workers-via-payroll">
    Run payroll for your active workers
  </Card>
</CardGroup>