Skip to main content

Documentation Index

Fetch the complete documentation index at: https://vanta.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
1

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.
Token is expired (one-hour lifetime), missing, or lacks vanta-api.all:read. Mint a fresh one — see Authentication → Tokens expire after one hour.
That person is already offboarded. Skip them — calling offboard on them is a no-op.
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.
2

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:
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.
Yes. Offboarding fails if the acknowledgerId belongs to a FORMER employee.
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.
3

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());
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.
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.
Your token has vanta-api.all:read but not vanta-api.all:write. Mint a token with both scopes.
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.