Offboarding

The offboarding endpoints let you create offboarding records and track their status from the outside - useful for HRIS integrations that kick off an offboarding the moment someone is marked as departing.

Base path: /api/v1/offboardings

List offboardings

GET /api/v1/offboardings

Required scope: offboardings:read

Query parameters

Param	Type	Description
`page`	integer	Page number (default: `1`)
`limit`	integer	Results per page (default: `20`, max: `100`)
`status`	string	Filter by status - see the list below
`department`	string	Filter by exact department match

Response 200 OK

{
  "data": [
    {
      "id": "3f9c8b1a-...",
      "employee_name": "Jordan Lee",
      "employee_email": "jordan@acme.com",
      "employee_role": "Senior Engineer",
      "employee_department": "Engineering",
      "exit_date": "2024-06-15",
      "status": "notice_period",
      "separation_type": "resignation",
      "created_at": "2024-05-28T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "total_pages": 1,
    "has_next": false
  }
}

Get an offboarding

GET /api/v1/offboardings/:id

Required scope: offboardings:read

Returns the same fields as the list endpoint, plus updated_at. Returns 404 if the ID isn't a valid UUID or doesn't belong to your organisation.

Create an offboarding

POST /api/v1/offboardings

Required scope: offboardings:write

Request body

{
  "employee_name": "Jordan Lee",
  "employee_email": "jordan@acme.com",
  "employee_role": "Senior Engineer",
  "employee_department": "Engineering",
  "exit_date": "2024-06-15",
  "separation_type": "resignation"
}

Field	Required	Type	Description
`employee_name`	✅	string	Full name (max 200 characters)
`exit_date`	✅	date (`YYYY-MM-DD`)	Last working day
`employee_email`	-	string	Work email (max 254 characters)
`employee_role`	-	string	Job title (max 100 characters)
`employee_department`	-	string	Department (max 100 characters)
`separation_type`	-	enum	See separation types below (default: `resignation`)

Separation types

resignation · termination · layoff · retirement · contract_end · other

New offboardings are always created with status: "pending" - there's no way to set the initial status via this call.

Response 201 Created - the created offboarding object (same shape as the list endpoint, without updated_at).

Creating an offboarding this way also notifies your organisation's admin and HR users in-app, the same as if it had been created from the dashboard.

Update offboarding status

PATCH /api/v1/offboardings/:id

Required scope: offboardings:write

The only thing this endpoint updates is status - there's no way to change employee details or other fields after creation.

Request body

{ "status": "it_revocation" }

Valid values: pending, in_progress, notice_period, it_revocation, asset_recovery, completed, cancelled. Any other value returns 400.

Response 200 OK

{
  "id": "3f9c8b1a-...",
  "employee_name": "Jordan Lee",
  "status": "it_revocation",
  "updated_at": "2024-06-02T14:30:00Z"
}

Note that the response only includes id, employee_name, status, and updated_at - not the full offboarding record. Fetch GET /offboardings/:id afterward if you need the rest.

There's currently no way to delete an offboarding or advance it through stages via the public API beyond setting status directly - stage gating and workflow automation (checklists, asset recovery, access revocation) happen inside the PurpletGo app itself.

Employees Offboarding Initiations