Offboard personnel

This guide completes the offboarding workflow for departed employees using POST /v1/people/offboard on the Manage Vanta API — deactivating unmonitored accounts, recording an acknowledger, and marking each person’s offboarding tasks complete. The build prompt below generates a daily job that drains the offboarding queue: it classifies every FORMER employee as already-complete, blocked, or eligible, then offboards the eligible ones in batches of up to 1000.

Before you begin

This guide is for Vanta admins managing data inside their own Vanta account. You’ll need:

A Manage Vanta API token.
The token must have scopes vanta-api.all:read and vanta-api.all:write.
For each person you’re offboarding, all of the following must already be true:
- Their employment status is FORMER.
- All monitored accounts are deactivated (this is automatic when an integration reports the deactivation).
- All custom offboarding tasks are complete.

POST /v1/people/offboard will mark unmonitored accounts deactivated and complete the offboarding for you. It will not auto-complete custom offboarding tasks — those have to be done in the Vanta UI before this call will succeed.

Wiring this into your HRIS? Run a daily job: query GET /v1/people?employmentStatusMatchesAny=FORMER, filter to people whose tasksSummary.status is not yet OFFBOARDING_COMPLETE, and call Step 3 in batches.

Find people eligible for offboarding

Your terminal — call GET /v1/people and filter to FORMER employees so you only see candidates. Inspect each person’s tasksSummary.status — anyone whose status is already OFFBOARDING_COMPLETE is done; anyone else with status: FORMER is a candidate.

Terminal

curl 'https://api.vanta.com/v1/people?pageSize=50&employmentStatusMatchesAny=FORMER' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response (truncated)

{
  "results": {
    "data": [
      {
        "id": "635c369a274dff2743f29160",
        "emailAddress": "former-employee@example.com",
        "name": { "display": "Adrian Test" },
        "employment": { "status": "FORMER", "endDate": "2024-09-21T00:00:00.000Z" },
        "tasksSummary": { "status": "OVERDUE" }
      }
    ]
  }
}

Copy the id of each candidate — you’ll send them in Step 3.

Got a 401?

Token is expired (one-hour lifetime), missing, or lacks vanta-api.all:read. Mint a fresh one — see Authentication → Token expiration.

tasksSummary.status is OFFBOARDING_COMPLETE?

That person is already offboarded. Skip them — calling offboard on them is a no-op.

Person still has custom offboarding tasks open?

POST /v1/people/offboard will fail until those are completed. Finish them on the Personnel page (or via your HRIS workflow) before calling Step 3.

Pick an acknowledger

Your terminal — every offboarding event records who acknowledged it (typically a security or HR admin). The acknowledgerId is not a Person id — it’s the Vanta User Account ID of a CURRENT employee. Get it from either:

GET /v1/users, or
the userId field on a person returned from GET /v1/people.

Terminal

curl 'https://api.vanta.com/v1/users?pageSize=10' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy the user id of the acknowledger you’ll record on every entry. Most teams hard-code this to a specific compliance lead’s user ID.

Acknowledger must be CURRENT?

Yes. Offboarding fails if the acknowledgerId belongs to a FORMER employee.

Why isn't this the Person id?

acknowledgerId refers to the Vanta User Account ID, not the Person ID. Pull it from GET /v1/users or from the userId field on the corresponding person record.

Offboard the people

Your terminal — POST /v1/people/offboard with an updates array. Each entry needs the person id and the acknowledgerId you picked.

const ACKNOWLEDGER_ID = "5df91759d463fd48218e9f15";

const res = await fetch("https://api.vanta.com/v1/people/offboard", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_TOKEN",
  },
  body: JSON.stringify({
    updates: [
      { id: "635c369a274dff2743f29160", acknowledgerId: ACKNOWLEDGER_ID },
      { id: "65a0caf8b4c7501f891e2183", acknowledgerId: ACKNOWLEDGER_ID },
    ],
  }),
});
console.log(await res.json());

import requests

ACKNOWLEDGER_ID = "5df91759d463fd48218e9f15"
ids = ["635c369a274dff2743f29160", "65a0caf8b4c7501f891e2183"]

r = requests.post(
    "https://api.vanta.com/v1/people/offboard",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "updates": [
            {"id": person_id, "acknowledgerId": ACKNOWLEDGER_ID}
            for person_id in ids
        ]
    },
)
r.raise_for_status()
print(r.json())

curl -X POST 'https://api.vanta.com/v1/people/offboard' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "updates": [
      { "id": "635c369a274dff2743f29160", "acknowledgerId": "5df91759d463fd48218e9f15" },
      { "id": "65a0caf8b4c7501f891e2183", "acknowledgerId": "5df91759d463fd48218e9f15" }
    ]
  }'

Expected response (200) — a per-person result so you can see which offboardings succeeded:

{
  "results": [
    { "id": "635c369a274dff2743f29160", "status": "SUCCESS" },
    { "id": "65a0caf8b4c7501f891e2183", "status": "ERROR", "message": "Custom offboarding task incomplete" }
  ]
}

Up to 1000 people per call. Successful entries are committed even if other entries return ERROR — fix and retry only the failures.

Got an ERROR saying tasks are incomplete?

The person still has open custom offboarding tasks or monitored accounts that haven’t deactivated. Resolve those (typically by waiting for the next sync from your IDP/MDM) and retry just that id.

Got a 403?

Your token has vanta-api.all:read but not vanta-api.all:write. Mint a token with both scopes.

Need to confirm a single person was offboarded?

Re-call GET /v1/people/{personId}. The tasksSummary.status flips to OFFBOARDING_COMPLETE when the offboarding is recorded.

Reassigning their controls first? Run Assign a control owner for everything they own before this call so nothing ends up orphaned to a FORMER user.

Congratulations

You’ve completed the offboarding workflow for one or more ex-employees. Their unmonitored accounts are now marked deactivated, an acknowledger is recorded for the audit log, and their tasksSummary.status is OFFBOARDING_COMPLETE.

Next steps

Assign a control owner

Reassign every control the offboarded person owned before they leave the system.

List overdue security tasks

Confirm the offboarded user no longer appears in your overdue-task report.

Try it in Postman

Import the collection and run offboard against a sandbox in seconds.

Manage Vanta API reference

Browse every Manage Vanta endpoint — controls, tests, documents, people.

Get Started

Guides

Concepts

Build for Vanta customers

Tools and Platform

Before you begin

Congratulations

Next steps

Assign a control owner

List overdue security tasks

Try it in Postman

Manage Vanta API reference

​Before you begin

​Congratulations

​Next steps

Assign a control owner

List overdue security tasks

Try it in Postman

Manage Vanta API reference

Before you begin

Congratulations

Next steps