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 scope vanta-api.all:read.
  • At least one source of personnel data connected to Vanta (HRIS, IDP, or manually added users).
Vanta tracks recurring security tasks for every person in your organization — security training, policy acceptance, custom checklists, background checks, and device-monitoring installs. The People endpoint lets you filter for people whose tasks are OVERDUE, then chase them down.
Wiring this into a recurring nudge (Slack reminder, email digest)? Run Step 1 on a schedule and feed the output into your notifier. Tokens expire hourly — re-mint at the top of each run.
1

Query overdue tasks for current employees

Your terminal — call GET /v1/people with taskTypeMatchesAny for the task types you care about, taskStatusMatchesAny=OVERDUE, and employmentStatusMatchesAny=CURRENT so you don’t chase former employees.
Terminal
curl 'https://api.vanta.com/v1/people?pageSize=50&employmentStatusMatchesAny=CURRENT&taskStatusMatchesAny=OVERDUE&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response (truncated for readability)
{
  "results": {
    "data": [
      {
        "id": "5fc82421a228f6b6f713547d",
        "emailAddress": "alex@example.com",
        "name": { "display": "Alex Admin" },
        "employment": { "status": "CURRENT", "jobTitle": "Engineer" },
        "tasksSummary": {
          "status": "OVERDUE",
          "dueDate": "2024-05-12T04:31:54.490Z",
          "details": {
            "completeTrainings": { "status": "OVERDUE", "incompleteTrainings": [{ "name": "AI_RISK_SECURITY_TRAINING" }] },
            "acceptPolicies": { "status": "OVERDUE", "unacceptedPolicies": [{ "name": "Secure Development Policy" }] },
            "completeBackgroundChecks": { "status": "COMPLETE" }
          }
        }
      }
    ],
    "pageInfo": { "hasNextPage": true, "endCursor": "..." }
  }
}
tasksSummary.details breaks down each task type so you can build a precise nudge (“you owe AI Risk training and one policy acceptance”) rather than a generic “you have overdue tasks” message.
Token is expired (one-hour lifetime), missing, or lacks vanta-api.all:read. Mint a fresh one — see Authentication → Tokens expire after one hour.
COMPLETE_TRAININGS, ACCEPT_POLICIES, COMPLETE_CUSTOM_TASKS, COMPLETE_CUSTOM_OFFBOARDING_TASKS, INSTALL_DEVICE_MONITORING, COMPLETE_BACKGROUND_CHECKS. Pass each one as a separate taskTypeMatchesAny= query param.
COMPLETE, DUE_SOON, OVERDUE, NONE. taskStatusMatchesAny is required when you pass taskTypeMatchesAny.
You omitted employmentStatusMatchesAny=CURRENT. The endpoint returns all matches by default, including offboarded people whose tasks were never completed.
2

Process and act on the results

Your terminal — paginate with pageCursor if hasNextPage is true, then collapse each person’s tasksSummary.details down to the specific items they owe.
const URL =
  "https://api.vanta.com/v1/people?pageSize=50" +
  "&employmentStatusMatchesAny=CURRENT" +
  "&taskStatusMatchesAny=OVERDUE" +
  "&taskTypeMatchesAny=COMPLETE_TRAININGS" +
  "&taskTypeMatchesAny=ACCEPT_POLICIES" +
  "&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS" +
  "&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS" +
  "&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING";

const res = await fetch(URL, {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
});
const { results } = await res.json();

const overdue = results.data.map((person) => ({
  name: person.name.display,
  email: person.emailAddress,
  overdueTasks: Object.entries(person.tasksSummary?.details ?? {})
    .filter(([, task]) => task.status === "OVERDUE")
    .map(([type]) => type),
}));

console.log(overdue);
Example collapsed output:
[
  {
    "name": "Alex Admin",
    "email": "alex@example.com",
    "overdueTasks": ["completeTrainings", "acceptPolicies"]
  }
]
That person has no tasks assigned (e.g. a contractor or service account marked as not-a-person). Skip them. See Mark accounts as not a person.
Read results.pageInfo.endCursor and hasNextPage. Re-call the endpoint with pageCursor=<endCursor> until hasNextPage is false. Don’t try to fetch all people in one call — pageSize caps at 100.
Just want a count, not the list? The same query returns pageInfo.hasNextPage plus a data array — paginate to count, or filter more aggressively (e.g. by single taskTypeMatchesAny) for a smaller response.

​
Congratulations

You’ve pulled the canonical list of current employees with overdue security tasks straight from Vanta. Wire this into a Slack nudge, email digest, or compliance dashboard so reminders happen without anyone clicking through the Vanta UI.

​
Next steps

Mark accounts as not a person

Exclude shared mailboxes and service accounts from these task tallies.

Offboard people

Once an employee is FORMER, complete the offboarding programmatically.

Try it in Postman

Import the collection and run the People query against a sandbox in seconds.

Manage Vanta API reference

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