Copy the prompt to run this live via the MCP server or have AI generate a runnable script.
{children}
;
export const OFFBOARD_BUILD = "You are writing a production-quality Node.js 18+ script that runs on a daily schedule (cron / GitHub Actions / Cloud Scheduler) to drain the offboarding queue for FORMER employees in Vanta. Use the Manage Vanta API (base URL https://api.vanta.com).\n\nSteps:\n\n1. Read VANTA_CLIENT_ID, VANTA_CLIENT_SECRET, and ACKNOWLEDGER_EMAIL from env. Also accept STATE_PATH (default ./.vanta-offboard-state.json) and DRY_RUN (default \"false\"). Fail fast on stderr if any required var is missing — do not hard-code an email or user id in the script.\n2. Mint a Vanta API token via POST https://api.vanta.com/oauth/token with Content-Type: application/json and a JSON body containing client_id, client_secret, grant_type=\"client_credentials\", and scope=\"vanta-api.all:read vanta-api.all:write\". The scope field is required — omitting it returns invalid_scope. Read access_token from the response. Re-mint at the start of each run (tokens expire after one hour).\n3. Resolve ACKNOWLEDGER_EMAIL to a user id by paging GET https://api.vanta.com/v1/people?employmentStatusMatchesAny=CURRENT&pageSize=100 with the pageCursor request param (read results.pageInfo.endCursor and hasNextPage until hasNextPage is false). Match emailAddress case-insensitively and capture the id as ACKNOWLEDGER_ID. Exit non-zero if not found, or if employment.status is not CURRENT (offboarding fails on a FORMER acknowledger).\n4. Page through GET https://api.vanta.com/v1/people?employmentStatusMatchesAny=FORMER&pageSize=100 using pageCursor pagination. For each person, classify as:\n - already-complete — tasksSummary.status === \"OFFBOARDING_COMPLETE\"\n - blocked — tasksSummary.details has any entry with status !== \"COMPLETE\" for completeCustomOffboardingTasks, or any monitored-account-related tasks not yet completed\n - eligible — everyone else\n5. Load STATE_PATH if present — { \"alreadyOffboarded\": [personId, ...] } — and remove those from \"eligible\".\n6. Print the plan: personId | displayName | emailAddress | endDate | classification | blockers (if any).\n7. If DRY_RUN === \"true\", print a JSON summary line and exit 0 without writing.\n8. Batch eligible people into chunks of 1000 and POST each chunk to https://api.vanta.com/v1/people/offboard with body { \"updates\": [{ \"id\": \"\", \"acknowledgerId\": \"\" }, ...] }. Issue chunks sequentially.\n9. Parse the per-entry results array. For every entry where status === \"SUCCESS\" append the id to alreadyOffboarded; write STATE_PATH atomically (temp file + rename) after every batch so a crash doesn't lose progress. For every \"ERROR\" entry, log id, displayName, and the message field — do not throw.\n10. Print one line per processed person: emailAddress | displayName | endDate | classification | status (SUCCESS / ERROR / BLOCKED / SKIPPED) | message (if any).\n11. End with a single JSON summary line on stdout: {\"total\": N, \"offboarded\": O, \"blocked\": B, \"alreadyComplete\": C, \"errors\": E}.\n\nSample API response item from GET /v1/people (use these field names exactly):\n{ \"id\": \"635c369a274dff2743f29160\", \"emailAddress\": \"former-employee@example.com\", \"name\": { \"display\": \"Adrian Test\", \"first\": \"Adrian\", \"last\": \"Test\" }, \"employment\": { \"status\": \"FORMER\", \"jobTitle\": \"Engineer\", \"startDate\": \"2022-01-01T00:00:00.000Z\", \"endDate\": \"2024-09-21T00:00:00.000Z\" }, \"tasksSummary\": { \"status\": \"OVERDUE\", \"dueDate\": \"2024-09-28T00:00:00.000Z\", \"details\": { \"completeCustomOffboardingTasks\": { \"status\": \"OVERDUE\" } } } }\n\nSample API response from POST /v1/people/offboard:\n{ \"results\": [{ \"id\": \"635c369a274dff2743f29160\", \"status\": \"SUCCESS\" }, { \"id\": \"65a0caf8b4c7501f891e2183\", \"status\": \"ERROR\", \"message\": \"Custom offboarding task incomplete\" }] }\n\nMissing-field handling: if tasksSummary is null treat as \"blocked\" with reason \"no tasks summary\"; if endDate is null print \"—\". Never throw on a missing optional field.\n\nError handling:\n- 401: re-mint once and retry the request.\n- 400: log the offending request body and exit non-zero.\n- 403: scope missing vanta-api.all:write. Log and exit non-zero.\n- 429: respect Retry-After if present, otherwise sleep 5s; retry up to 3 times.\n- 5xx: retry with 2s exponential back-off, max 3 attempts; then log and exit non-zero.\n\nDo not:\n- Add external dependencies — use built-in fetch, fs, and path only.\n- Hard-code any person id, email, or acknowledger id — every customer's personnel list is different. Read ACKNOWLEDGER_EMAIL from env and discover everything else via the API.\n- Apply changes when DRY_RUN is \"true\".\n- Cache the access token across runs.\n- Send more than 1000 entries per /v1/people/offboard call.\n- Silently swallow errors.\n\nDone when: a follow-up run reports 0 eligible candidates (every FORMER employee is OFFBOARDING_COMPLETE or blocked). Exit 0 if errors === 0; otherwise exit 1.\n\nScope required: vanta-api.all:read vanta-api.all:write.";
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](/docs/quickstart/manage-vanta).
* 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.
**Your terminal** — call [`GET /v1/people`](/reference/manage-vanta/overview) 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.
```bash Terminal theme={"system"}
curl 'https://api.vanta.com/v1/people?pageSize=50&employmentStatusMatchesAny=FORMER' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'
```
Response (truncated)
```json theme={"system"}
{
"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 → Token expiration](/docs/concepts/authentication#token-expiration).
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](https://app.vanta.com/people/people) (or via your HRIS workflow) before calling Step 3.
**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`](/reference/manage-vanta/overview), or
* the `userId` field on a person returned from [`GET /v1/people`](/reference/manage-vanta/overview).
```bash Terminal theme={"system"}
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.
**Your terminal** — `POST /v1/people/offboard` with an `updates` array. Each entry needs the person `id` and the `acknowledgerId` you picked.
```javascript Node.js theme={"system"}
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());
```
```python Python theme={"system"}
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())
```
```bash Terminal theme={"system"}
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:
```json theme={"system"}
{
"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}`](/reference/manage-vanta/overview). The `tasksSummary.status` flips to `OFFBOARDING_COMPLETE` when the offboarding is recorded.
**Reassigning their controls first?** Run [Assign a control owner](/docs/guides/add-an-owner-to-a-control) 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
Reassign every control the offboarded person owned before they leave the system.
Confirm the offboarded user no longer appears in your overdue-task report.
Import the collection and run `offboard` against a sandbox in seconds.
Browse every Manage Vanta endpoint — controls, tests, documents, people.