Vendors

Start assessment

Starts an assessment for the specified vendor and assessment type. Creates an assessment if needed, or starts an eligible existing assessment. Assessments associated with security incidents cannot be started through this endpoint.

Requires both the vendors:view and vendors_data:manage organization permissions: vendors:view to read the assessment type and vendors_data:manage to start the assessment.

Returns 403 Forbidden when the caller lacks either permission. Returns 404 Not Found when the vendor or the assessment type does not exist in the customer’s organization. Returns 422 Unprocessable Entity when an eligible assessment cannot be started, including when it is already in progress.

POST

vendors

{vendorId}

assessments

Start assessment

curl --request POST \
  --url https://api.vanta.com/v1/vendors/{vendorId}/assessments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assessmentTypeId": "<string>"
}
'

import requests

url = "https://api.vanta.com/v1/vendors/{vendorId}/assessments"

payload = { "assessmentTypeId": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({assessmentTypeId: '<string>'})
};

fetch('https://api.vanta.com/v1/vendors/{vendorId}/assessments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vanta.com/v1/vendors/{vendorId}/assessments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assessmentTypeId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vanta.com/v1/vendors/{vendorId}/assessments"

	payload := strings.NewReader("{\n  \"assessmentTypeId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vanta.com/v1/vendors/{vendorId}/assessments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assessmentTypeId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vanta.com/v1/vendors/{vendorId}/assessments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assessmentTypeId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "a2f7e1b9d0c3f4e5a6c7b8d8",
  "vendorId": "6696e9bca247cbdf1c8e5054",
  "status": "COMPLETED",
  "audience": "EXTERNAL",
  "completedByUserId": "6696ea0595df50d5cd6ec3b7",
  "startDate": "2024-02-01T00:00:00.000Z",
  "dueDate": "2024-03-01T00:00:00.000Z",
  "overrideDueDate": "2024-03-15T00:00:00.000Z",
  "completionDate": "2024-03-10T00:00:00.000Z",
  "createdDate": "2024-01-25T00:00:00.000Z",
  "decision": {
    "status": "APPROVED",
    "lastUpdatedAt": "2024-03-17T00:00:00.000Z",
    "comments": "No major concerns, limited sharing of data, low security risk."
  },
  "assessmentType": {
    "id": "6696ea0595df50d5cd6ec3b8",
    "name": "Security",
    "description": null
  },
  "owner": {
    "id": "6696ea0595df50d5cd6ec3b9",
    "type": "USER",
    "displayName": "Jane Doe",
    "email": "jane.doe@example.com"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

vendorId

string

required

Body

application/json

assessmentTypeId

string

required

ID of the assessment type to start for this vendor.

Pattern: ^[0-9a-fA-F]{24}$

Response

200 - application/json

string

required

Unique identifier for the assessment.

vendorId

string

required

Unique identifier for the vendor.

status

enum<string>

required

The lifecycle status of the assessment.

Available options:

NOT_STARTED,

IN_PROGRESS,

COMPLETED

audience

enum<string>

required

Who fills out this assessment.

Available options:

EXTERNAL,

INTERNAL

completedByUserId

string | null

required

The Vanta user ID of the person who completed this assessment.

startDate

string<date-time> | null

required

The timestamp of when the assessment was started.

dueDate

string<date-time> | null

required

The timestamp of when the assessment is due.

overrideDueDate

string<date-time> | null

required

A manual override timestamp of when the assessment is due.

completionDate

string<date-time> | null

required

The timestamp of when the assessment was marked as completed.

createdDate

string<date-time>

required

The timestamp of when the assessment was created.

decision

object | null

required

An object containing information about the decision of the assessment.

Show child attributes

assessmentType

object

required

The assessment type for this assessment.

Show child attributes

owner

object | null

required

The owner of this assessment, if assigned.

Show child attributes

⌘I

Start assessment

curl --request POST \
  --url https://api.vanta.com/v1/vendors/{vendorId}/assessments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assessmentTypeId": "<string>"
}
'

import requests

url = "https://api.vanta.com/v1/vendors/{vendorId}/assessments"

payload = { "assessmentTypeId": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({assessmentTypeId: '<string>'})
};

fetch('https://api.vanta.com/v1/vendors/{vendorId}/assessments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vanta.com/v1/vendors/{vendorId}/assessments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'assessmentTypeId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vanta.com/v1/vendors/{vendorId}/assessments"

	payload := strings.NewReader("{\n  \"assessmentTypeId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vanta.com/v1/vendors/{vendorId}/assessments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"assessmentTypeId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vanta.com/v1/vendors/{vendorId}/assessments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"assessmentTypeId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "a2f7e1b9d0c3f4e5a6c7b8d8",
  "vendorId": "6696e9bca247cbdf1c8e5054",
  "status": "COMPLETED",
  "audience": "EXTERNAL",
  "completedByUserId": "6696ea0595df50d5cd6ec3b7",
  "startDate": "2024-02-01T00:00:00.000Z",
  "dueDate": "2024-03-01T00:00:00.000Z",
  "overrideDueDate": "2024-03-15T00:00:00.000Z",
  "completionDate": "2024-03-10T00:00:00.000Z",
  "createdDate": "2024-01-25T00:00:00.000Z",
  "decision": {
    "status": "APPROVED",
    "lastUpdatedAt": "2024-03-17T00:00:00.000Z",
    "comments": "No major concerns, limited sharing of data, low security risk."
  },
  "assessmentType": {
    "id": "6696ea0595df50d5cd6ec3b8",
    "name": "Security",
    "description": null
  },
  "owner": {
    "id": "6696ea0595df50d5cd6ec3b9",
    "type": "USER",
    "displayName": "Jane Doe",
    "email": "jane.doe@example.com"
  }
}

API Basics

Manage API

Integrations API

Audit API

Webhooks

Start assessment

Authorizations

Path Parameters

Body

Response