Mark accounts as not a person

Exclude shared mailboxes, service accounts, and test accounts from Vanta’s onboarding checklists and personnel tests, using the Manage Vanta API.

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.
• The accounts you want to exclude already exist in Vanta (most often pulled in from your IDP).

People in Vanta are user accounts in scope for an audit. Some accounts pulled in via IDP sync — shared mailing lists, service accounts, CI bots, test accounts — aren’t real people. Marking them “not a person” excludes them from onboarding checklists, training assignments, policy acceptance, and any other personnel-related test.

Made a mistake and need to undo? Use POST /v1/people/mark-as-people with the same updates shape (no reason required) to restore them.

1. Find the account IDs

   Your terminal — call GET /v1/people and locate the accounts you want to exclude. Filtering by q (partial match on email or name) is usually fastest.

   Terminal

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

   Response

   {
     "results": {
       "data": [
         {
           "id": "640b888ba7e831e41f0d6cb6",
           "emailAddress": "[e-mail]",
           "name": { "display": "Support Inbox" },
           "employment": { "status": "CURRENT", "jobTitle": null }
         }
       ]
     }
   }
   

   Copy each id you want to exclude — you’ll send them in Step 2. You can also copy a person’s ID directly from the URL on the People page.

   Got a 401?

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

   Can't find the account?

   Filter client-side by emailAddress or paginate with pageCursor if hasNextPage is true. If the account is missing entirely, your IDP hasn’t synced it yet — wait one sync cycle or trigger a refresh from the Integrations page.

2. Mark the accounts as not a person

   Your terminal — POST /v1/people/mark-as-not-people with an updates array. Each entry needs the person id and a short reason that’s stored alongside the change in your audit log.

   Node.js

   const res = await fetch(
     "https://api.vanta.com/v1/people/mark-as-not-people",
     {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: "Bearer YOUR_TOKEN",
       },
       body: JSON.stringify({
         updates: [
           { id: "640b888ba7e831e41f0d6cb6", reason: "Shared mailing list" },
           { id: "65a0caf8b4c7501f891e2183", reason: "CI service account" },
         ],
       }),
     },
   );
   console.log(await res.json());
   

   Expected response (200) — a per-account result, so you can tell exactly which entries failed:

   {
     "results": [
       { "id": "640b888ba7e831e41f0d6cb6", "status": "SUCCESS" },
       { "id": "65a0caf8b4c7501f891e2183", "status": "SUCCESS" }
     ]
   }
   

   Up to 100 accounts per call. Batch larger lists across multiple requests.

   Got an `ERROR` in `results`?

   The message field tells you why a specific entry failed — typically because the id doesn’t exist, or the account is already marked as not-a-person. Successful entries are still applied; only fix and retry the failures.

   Got a 403?

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

   Need to undo?

   Call POST /v1/people/mark-as-people with { "updates": [{ "id": "..." }] } — no reason is required to restore.

Tip. You can verify a change took effect by re-calling GET /v1/people/{personId} — the account will be excluded from the default data array on GET /v1/people going forward.

Congratulations

You’ve excluded shared mailboxes, service accounts, or other non-human accounts from Vanta’s personnel tracking. Those accounts won’t get assigned trainings, policy acceptances, or background checks, and they won’t show up as failures on personnel-related tests.

Next steps

List overdue security tasks

Now that the noise is filtered out, see who actually has overdue work.

Offboard people

For real ex-employees, complete the offboarding programmatically.

Try it in Postman

Import the collection and run mark-as-not-people against a sandbox in seconds.

Manage Vanta API reference

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