List people with overdue security tasks

Query a list of current employees with overdue security tasks

List People with OVERDUE Tasks

This guide will help you list people who have tasks with the status OVERDUE using the Vanta API.

Steps:

  • Authenticate with the Vanta API.
  • Use the ListPeople endpoint with the appropriate query parameters to filter for overdue tasks.
  • Handle the response post request and filter records by employee status.


List People Endpoint

This endpoint retrieves a list of people in your Vanta instance, optionally filtered by task status.

Endpoint:

/people

Query Parameters:

  • taskTypeMatchesAny (optional): <stringEnum> Filter people by task type. This param represents a task type and can be any of the following below:
- COMPLETE_TRAININGS
- ACCEPT_POLICIES
- COMPLETE_CUSTOM_TASKS
- COMPLETE_CUSTOM_OFFBOARDING_TASKS
- INSTALL_DEVICE_MONITORING
- COMPLETE_BACKGROUND_CHECKS
  • taskStatusMatchesAny (optional): <stringEnum>. This param is required when also using taskTypeMatchesAny. Filter people by task status. To list people with overdue tasks, use OVERDUE. This param can be any of the following:
- COMPLETE
- DUE_SOON
- OVERDUE
- NONE

For any Security Tasks with an Overdue status, use the following Query Parameters:

&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS
&taskTypeMatchesAny=ACCEPT_POLICIES
&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS
&taskTypeMatchesAny=COMPLETE_TRAININGS
&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING
&taskStatusMatchesAny=OVERDUE
  • pageSize (<number>): An integer value that specifies the number of resources to return per page.
  • pageCursor (<string>): A string value used to navigate through pages of results.

List People - Code Example

curl --location 'https://api.vanta.com/v1/people?pageSize=50&pageCursor=%3Cstring%3E&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING&taskStatusMatchesAny=OVERDUE' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer vat_YOUR_TOKEN_HERE'
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Authorization", "Bearer vat_YOUR_TOKEN_HERE");

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

fetch("https://api.vanta.com/v1/people?pageSize=50&pageCursor=<string>&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING&taskStatusMatchesAny=OVERDUE", 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?pageSize=50&pageCursor=<string>&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING&taskStatusMatchesAny=OVERDUE',
  headers: { 
    'Accept': 'application/json', 
    'Authorization': 'Bearer vat_YOUR_TOKEN_HERE'
  }
};

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?pageSize=50&pageCursor=<string>&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING&taskStatusMatchesAny=OVERDUE"

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

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

print(response.text)


List People - Example Response

For a detailed breakdown of the fields in the response object below see this guide.

{
    "results": {
        "pageInfo": {
            "endCursor": "NjIzY2UxZDcyNDhhOGIyNmRmNzk0ODg1",
            "hasNextPage": true,
            "hasPreviousPage": false,
            "startCursor": "NWZjODI0MjFhMjI4ZjZiNmY3MTM1NDdk"
        },
        "data": [
            {
                "id": "5fc82421a228f6b6f713547d",
                "emailAddress": "[email protected]",
                "employment": {
                    "endDate": null,
                    "jobTitle": null,
                    "startDate": "2022-04-01T16:00:00.000Z",
                    "status": "CURRENT"
                },
                "leaveInfo": null,
                "name": {
                    "display": "admin admin",
                    "last": "admin",
                    "first": "admin"
                },
                "groupIds": [
                    "659d48981d1cdbc9b445faf9"
                ],
                "sources": {
                    "emailAddress": {
                        "integrationId": "okta",
                        "resourceId": "664f22393a3cc20954efeb68",
                        "type": "INTEGRATION"
                    },
                    "employment": {
                        "startDate": {
                            "type": "VANTA"
                        },
                        "endDate": {
                            "integrationId": "okta",
                            "resourceId": "664f22393a3cc20954efeb68",
                            "type": "INTEGRATION"
                        }
                    }
                },
                "tasksSummary": {
                    "completionDate": null,
                    "dueDate": "2022-04-02T16:00:00.000Z",
                    "status": "OVERDUE",
                    "details": {
                        "completeTrainings": {
                            "taskType": "COMPLETE_TRAININGS",
                            "status": "OVERDUE",
                            "dueDate": "2024-06-09T22:34:59.325Z",
                            "completionDate": null,
                            "disabled": null,
                            "incompleteTrainings": [
                                {
                                    "name": "AI_RISK_SECURITY_TRAINING"
                                }
                            ],
                            "completedTrainings": [
                                {
                                    "name": "GENERAL_SECURITY_TRAINING"
                                },
                                {
                                    "name": "GDPR_SECURITY_TRAINING"
                                },
                                {
                                    "name": "CCPA_SECURITY_TRAINING"
                                }
                            ]
                        },
                        "completeCustomTasks": {
                            "taskType": "COMPLETE_CUSTOM_TASKS",
                            "incompleteCustomTasks": [
                                {
                                    "name": "CUSTOM_CHECKLIST_TASK"
                                },
                                {
                                    "name": "CUSTOM_CHECKLIST_TASK"
                                }
                            ],
                            "completedCustomTasks": [],
                            "status": "OVERDUE",
                            "completionDate": null,
                            "dueDate": "2022-04-02T16:00:00.000Z",
                            "disabled": null
                        },
                        "completeOffboardingCustomTasks": {
                            "completedCustomOffboardingTasks": [],
                            "completionDate": null,
                            "disabled": null,
                            "dueDate": null,
                            "incompleteCustomOffboardingTasks": [],
                            "status": "NONE",
                            "taskType": "COMPLETE_CUSTOM_OFFBOARDING_TASKS"
                        },
                        "completeBackgroundChecks": {
                            "taskType": "COMPLETE_BACKGROUND_CHECKS",
                            "status": "COMPLETE",
                            "completionDate": null,
                            "dueDate": null,
                            "disabled": {
                                "date": "2024-06-12T17:26:34.593Z",
                                "reason": "nn"
                            }
                        },
                        "acceptPolicies": {
                            "taskType": "ACCEPT_POLICIES",
                            "status": "OVERDUE",
                            "dueDate": "2024-05-12T04:31:54.490Z",
                            "completionDate": null,
                            "disabled": null,
                            "unacceptedPolicies": [
                                {
                                    "name": "AAA NEW ADG Test policy 3.0"
                                },
                                {
                                    "name": "ADG Test policy2"
                                },
                                {
                                    "name": "Alex Custom Policy"
                                }
                            ],
                            "acceptedPolicies": [
                                {
                                    "name": "Secure Development Policy"
                                },
                                {
                                    "name": "Vance Drive Sync Test"
                                },
                                {
                                    "name": "01-ISMS Scope of the ISMS"
                                }
                            ]
                        },
                        "installDeviceMonitoring": {
                            "taskType": "INSTALL_DEVICE_MONITORING",
                            "status": "NONE",
                            "completionDate": null,
                            "dueDate": null,
                            "disabled": null
                        }
                    }
                }
            },
            {
                "id": "659d5d7479202eb02c059f12",
                "emailAddress": "[email protected]",
                "employment": {
                    "endDate": "2024-04-24T11:51:39.582Z",
                    "jobTitle": null,
                    "startDate": "2024-01-09T14:51:10.274Z",
                    "status": "FORMER"
                },
                "leaveInfo": null,
                "name": {
                    "display": "Admin Test DB Error Alex",
                    "last": "Alex",
                    "first": "Admin Test DB Error"
                },
                "groupIds": [
                    "659d48981d1cdbc9b445faf9"
                ],
                "sources": {
                    "emailAddress": {
                        "type": "VANTA"
                    },
                    "employment": {
                        "startDate": {
                            "type": "VANTA"
                        },
                        "endDate": {
                            "type": "VANTA"
                        }
                    }
                },
                "tasksSummary": {
                    "completionDate": "2024-06-03T22:04:29.513Z",
                    "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": "GDPR_SECURITY_TRAINING"
                                },
                                {
                                    "name": "CCPA_SECURITY_TRAINING"
                                },
                                {
                                    "name": "AI_RISK_SECURITY_TRAINING"
                                }
                            ],
                            "completedTrainings": []
                        },
                        "completeCustomTasks": {
                            "taskType": "COMPLETE_CUSTOM_TASKS",
                            "incompleteCustomTasks": [
                                {
                                    "name": "CUSTOM_CHECKLIST_TASK"
                                },
                                {
                                    "name": "CUSTOM_CHECKLIST_TASK"
                                }
                            ],
                            "completedCustomTasks": [],
                            "status": "OVERDUE",
                            "completionDate": null,
                            "dueDate": "2024-01-10T14:51:10.274Z",
                            "disabled": null
                        },
                        "completeOffboardingCustomTasks": {
                            "completedCustomOffboardingTasks": [],
                            "completionDate": null,
                            "disabled": null,
                            "dueDate": null,
                            "incompleteCustomOffboardingTasks": [],
                            "status": "NONE",
                            "taskType": "COMPLETE_CUSTOM_OFFBOARDING_TASKS"
                        },
                        "completeBackgroundChecks": {
                            "taskType": "COMPLETE_BACKGROUND_CHECKS",
                            "status": "DUE_SOON",
                            "completionDate": null,
                            "dueDate": null,
                            "disabled": null
                        },
                        "acceptPolicies": {
                            "taskType": "ACCEPT_POLICIES",
                            "status": "DUE_SOON",
                            "dueDate": null,
                            "completionDate": null,
                            "disabled": null,
                            "unacceptedPolicies": [],
                            "acceptedPolicies": [
                                {
                                    "name": "AAA NEW ADG Test policy 3.0"
                                },
                                {
                                    "name": "ADG Test policy2"
                                },
                            ]
                        },
                        "installDeviceMonitoring": {
                            "taskType": "INSTALL_DEVICE_MONITORING",
                            "status": "NONE",
                            "completionDate": null,
                            "dueDate": null,
                            "disabled": null
                        }
                    }
                }
            }
        ]
    }
}


List People - Response Handling

The List People response includes all employees matching the task status query parameters used, including 'Former' employees. Use the employment.status property to determine the employees status, and filter accordingly.

const axios = require('axios');

let config = {
    method: 'get',
    maxBodyLength: Infinity,
    url: 'https://api.vanta.com/v1/people?pageSize=50&pageCursor=<string>&taskTypeMatchesAny=COMPLETE_BACKGROUND_CHECKS&taskTypeMatchesAny=ACCEPT_POLICIES&taskTypeMatchesAny=COMPLETE_CUSTOM_TASKS&taskTypeMatchesAny=COMPLETE_TRAININGS&taskTypeMatchesAny=INSTALL_DEVICE_MONITORING&taskStatusMatchesAny=OVERDUE',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer vat_TOKEN_HERE'
    }
};

axios.request(config)
    .then((response) => {
        let res = JSON.stringify(response.data);
        let resParse = JSON.parse(res);
        resParse.results.data.forEach((person) => {
            if (person.employment.status !== 'FORMER') {
                let personRecord = {
                    name: person.name.display,
                    tasks: []
                }
                let tasks = person.tasksSummary?.details;
                Object.values(tasks).forEach((task) => {
                    taskRecord = {
                        taskType: task.taskType,
                        status: task.status
                    }
                    personRecord.tasks.push(taskRecord);
                });
                console.dir(personRecord, { depth: null });
            }
        });
    })
    .catch((error) => {
        console.log(error);
    });

List People Response Handling - Example Output

{
  name: 'admin admin',
  tasks: [
    { taskType: 'COMPLETE_TRAININGS', status: 'OVERDUE' },
    { taskType: 'COMPLETE_CUSTOM_TASKS', status: 'OVERDUE' },
    { taskType: 'COMPLETE_CUSTOM_OFFBOARDING_TASKS', status: 'NONE' },
    { taskType: 'COMPLETE_BACKGROUND_CHECKS', status: 'COMPLETE' },
    { taskType: 'ACCEPT_POLICIES', status: 'OVERDUE' },
    { taskType: 'INSTALL_DEVICE_MONITORING', status: 'NONE' }
  ]
},
{
  name: 'Ben Ben',
  tasks: [
    { taskType: 'COMPLETE_TRAININGS', status: 'COMPLETE' },
    { taskType: 'COMPLETE_CUSTOM_TASKS', status: 'NONE' },
    {
      taskType: 'COMPLETE_CUSTOM_OFFBOARDING_TASKS',
      status: 'COMPLETE'
    },
    { taskType: 'COMPLETE_BACKGROUND_CHECKS', status: 'NONE' },
    { taskType: 'ACCEPT_POLICIES', status: 'OVERDUE' },
    { taskType: 'INSTALL_DEVICE_MONITORING', status: 'NONE' }
  ]
}