Vanta Developer Console
Docs

Offboard people

Once an employee's offboarding admin tasks are complete, you can mark unmonitored accounts deactivated, confirm the user offboarding.

Suggest Edits

Offboarding people

In order to offboard a single Employee or a list of Employees through this endpoint, employees must be eligible to be offboarded. This means they are currently in an offboarding state with in Vanta, have no incomplete Admin tasks associated, and all Monitored accounted marked deactivated( Should be automatic when deactivated in those Vanta connected integrations in most cases).

Using the /People/Offboard Endpoint will only mark any Unmonitored accounts deactivated, and Complete Offboarding.


Offboard Endpoint

The /People/Offboard Endpoint takes in a request body containing a List of Eligible users to offboard, and the acknowledging admin's user Id.

To retrieve a user's user Id, send a GET request to the list /people endpoint, or copy it from the URL when viewing that user on the Vanta portal's People page.

Endpoint:

/people/offboard

Request Body:

{
  "offboardingAcknowledgerId": "<string>",
  "employeeIds": [
    "<string>",
    "<string>"
  ]
}

Offboard - Code Example

View the request below. In this example, we're only offboarding a single employee, however you can offboard as many as you need.

curl --location 'https://api.vanta.com/v1/people/offboard' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_TOKEN' \
--data '{
  "offboardingAcknowledgerId": "5df91759d463fd48218e9f15",
  "employeeIds": [
"635c369a274dff2743f29160"
  ]
}'

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_TOKEN");

const raw = JSON.stringify({
  "offboardingAcknowledgerId": "5df91759d463fd48218e9f15",
  "employeeIds": [
    "635c369a274dff2743f29160"
  ]
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.vanta.com/v1/people/offboard", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

const axios = require('axios');
let data = JSON.stringify({
  "offboardingAcknowledgerId": "5df91759d463fd48218e9f15",
  "employeeIds": [
    "635c369a274dff2743f29160"
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.vanta.com/v1/people/offboard',
  headers: { 
    'Content-Type': 'application/json', 
    'Accept': 'application/json', 
    'Authorization': 'Bearer vat_TOKEN'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


import requests
import json

url = "https://api.vanta.com/v1/people/offboard"

payload = json.dumps({
  "offboardingAcknowledgerId": "5df91759d463fd48218e9f15",
  "employeeIds": [
    "635c369a274dff2743f29160"
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer vat_TOKEN'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Offboard - Example Response

If successful, your response should 200 and return the list of successfully offboarded users

{
    "offboardedPeople": [
        "635c369a274dff2743f29160"
    ]
}

Get Person Endpoint

You can then query these users with the GET /person:id Endpoint if needed.

Endpoint

/person:id

Path Variables

  • id: The employee userId in Vanta

Get Person - Code Example

curl --location 'https://api.vanta.com/v1/people/635c369a274dff2743f29160' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_TOKEN'

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_TOKEN");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow"
};

fetch("https://api.vanta.com/v1/people/635c369a274dff2743f29160", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.vanta.com/v1/people/635c369a274dff2743f29160',
  headers: { 
    'Accept': 'application/json', 
    'Authorization': 'Bearer vat_TOKEN'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


import requests

url = "https://api.vanta.com/v1/people/635c369a274dff2743f29160"

payload = {}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer vat_TOKEN'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Get Person - Example Response

The response from the Get person by ID endpoint is the full Employee schema, including task status and policy acceptance:

{
    "id": "635c369a274dff2743f29160",
    "emailAddress": "[email protected]",
    "employment": {
        "endDate": "2023-09-21T19:48:04.406Z",
        "jobTitle": null,
        "startDate": "2022-10-28T07:00:00.000Z",
        "status": "FORMER"
    },
    "name": {
        "display": "Adrian Test",
        "last": "Test",
        "first": "Adrian"
    },
    "groupIds": [
        "6042d90831b0ef1977131cf5",
        "654e4e99e527d4a47f7a5111",
    ],
    "sources": {
        "emailAddress": {
            "type": "VANTA"
        },
        "employment": {
            "startDate": {
                "type": "VANTA"
            },
            "endDate": {
                "type": "VANTA"
            }
        }
    },
    "tasksSummary": {
        "completionDate": "2024-05-01T01:01:57.685Z",
        "dueDate": null,
        "status": "OFFBOARDING_COMPLETE",
        "details": {
            "completeTrainings": {
                "taskType": "COMPLETE_TRAININGS",
                "status": "DUE_SOON",
                "dueDate": null,
                "completionDate": null,
                "disabled": null,
                "incompleteTrainings": [
                    {
                        "name": "GENERAL_SECURITY_TRAINING"
                    },
                    {
                        "name": "HIPAA_SECURITY_TRAINING"
                    },
                    {
                        "name": "PCI_SECURITY_TRAINING"
                    },
                    {
                        "name": "GDPR_SECURITY_TRAINING"
                    },
                    {
                        "name": "INSIDER_THREAT_SECURITY_TRAINING"
                    },
                    {
                        "name": "SECURE_CODE_SECURITY_TRAINING"
                    },
                    {
                        "name": "SOCIAL_ENGINEERING_SECURITY_TRAINING"
                    }
                ],
                "completedTrainings": []
            },
            "completeCustomTasks": {
                "taskType": "COMPLETE_CUSTOM_TASKS",
                "incompleteCustomTasks": [
                    {
                        "name": "CUSTOM_CHECKLIST_TASK"
                    },
                    {
                        "name": "CUSTOM_CHECKLIST_TASK"
                    },
                    {
                        "name": "CUSTOM_CHECKLIST_TASK"
                    },
                    {
                        "name": "CUSTOM_CHECKLIST_TASK"
                    },
                    {
                        "name": "CUSTOM_CHECKLIST_TASK"
                    }
                ],
                "completedCustomTasks": [],
                "status": "OVERDUE",
                "completionDate": null,
                "dueDate": "2022-12-09T07:00:00.000Z",
                "disabled": null
            },
            "completeOffboardingCustomTasks": {
                "taskType": "COMPLETE_CUSTOM_OFFBOARDING_TASKS",
                "incompleteCustomOffboardingTasks": [],
                "completedCustomOffboardingTasks": [
                    {
                        "name": "this is a custom task"
                    },
                    {
                        "name": "other task"
                    }
                ],
                "status": "COMPLETE",
                "completionDate": "2024-05-01T01:01:57.685Z",
                "dueDate": null,
                "disabled": null
            },
            "completeBackgroundChecks": {
                "taskType": "COMPLETE_BACKGROUND_CHECKS",
                "status": "NONE",
                "completionDate": null,
                "dueDate": null,
                "disabled": null
            },
            "acceptPolicies": {
                "taskType": "ACCEPT_POLICIES",
                "status": "DUE_SOON",
                "dueDate": null,
                "completionDate": null,
                "disabled": null,
                "unacceptedPolicies": [],
                "acceptedPolicies": [
                    {
                        "name": "Business Continuity and Disaster Recovery Plan"
                    },
                    {
                        "name": "GDPR Compliance Policy"
                    },
                    {
                        "name": "01-ISMS Scope of the ISMS"
                    }
                ]
            },
            "installDeviceMonitoring": {
                "taskType": "INSTALL_DEVICE_MONITORING",
                "status": "NONE",
                "completionDate": null,
                "dueDate": null,
                "disabled": null
            }
        }
    }
}

Get Person - Response Schema

Below is a bullet list explaining each property in the Get Person response body:

  • id: A unique identifier for the user.

  • emailAddress: The email address of the user.

employment: Details about the user's employment

  • endDate: The end date of the employment.
  • jobTitle: The job title of the user (null if not specified).
  • startDate: The start date of the employment.
  • status: The employment status of the user.

name: Details about the user's name

  • display: The display name of the user.
  • last: The last name of the user.
  • first: The first name of the user.

groupIds: An array of group IDs the user is part of

  • [ <string>, <string> ]

sources: Information about the sources of certain data

  • emailAddress:
    • type: The source type for the email address.
  • employment:
    • startDate:
      • type: The source type for the start date.
    • endDate:
      • type: The source type for the end date.

tasksSummary: Summary of the tasks related to the user

  • completionDate: The completion date of the tasks.
  • dueDate: The due date for the tasks (null if not specified).
  • status: The status of the tasks.

details: Detailed information about various tasks

  • completeTrainings: Details about training tasks
    • taskType: The type of task.
    • status: The status of the task.
    • dueDate: The due date for the task (null if not specified).
    • completionDate: The completion date of the task (null if not completed).
    • disabled: Indicates if the task is disabled (null if not specified).
    • incompleteTrainings: An array of incomplete training tasks
      • name: "GENERAL_SECURITY_TRAINING"
      • name: "HIPAA_SECURITY_TRAINING"
    • completedTrainings: An array of completed training tasks (empty in this case).
  • completeCustomTasks: Details about custom tasks
    • taskType: The type of task.
    • status: The status of the task.
    • completionDate: The completion date of the task (null if not completed).
    • dueDate: The due date for the task.
    • disabled: Indicates if the task is disabled (null if not specified).
    • incompleteCustomTasks: An array of incomplete custom tasks
      • name: "CUSTOM_CHECKLIST_TASK"
    • completedCustomTasks: An array of completed custom tasks (empty in this case).
  • completeOffboardingCustomTasks: Details about custom offboarding tasks
    • taskType: The type of task.
    • status: The status of the task.
    • completionDate: The completion date of the task.
    • dueDate: The due date for the task (null if not specified).
    • disabled: Indicates if the task is disabled (null if not specified).
    • incompleteCustomOffboardingTasks: An array of incomplete custom offboarding tasks (empty in this case).
    • completedCustomOffboardingTasks: An array of completed custom offboarding tasks
      • name: "this is a custom task"
      • name: "other task"
  • completeBackgroundChecks: Details about background check tasks
    • taskType: The type of task.
    • status: The status of the task.
    • completionDate: The completion date of the task (null if not completed).
    • dueDate: The due date for the task (null if not specified).
    • disabled: Indicates if the task is disabled (null if not specified).
  • acceptPolicies: Details about policy acceptance tasks
    • taskType: The type of task.
    • status: The status of the task.
    • dueDate: The due date for the task (null if not specified).
    • completionDate: The completion date of the task (null if not completed).
    • disabled: Indicates if the task is disabled (null if not specified).
    • unacceptedPolicies: An array of unaccepted policies (empty in this case).
    • acceptedPolicies: An array of accepted policies
      • name: "Business Continuity and Disaster Recovery Plan"
      • name: "GDPR Compliance Policy"
      • name: "01-ISMS Scope of the ISMS"
  • installDeviceMonitoring: Details about device monitoring installation tasks
    • taskType: The type of task.
    • status: The status of the task.
    • completionDate: The completion date of the task (null if not completed).
    • dueDate: The due date for the task (null if not specified).
    • disabled: Indicates if the task is disabled (null if not specified).

Updated 5 months ago