Create vendors with evidence

Add a vendor to your Vanta vendor inventory and attach a documentation file (SOC 2, DPA, security questionnaire, etc.), 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 evidence file you want to attach (PDF, DOCX, JPG, PNG, or XLSX) saved locally.

Bulk-importing vendors from a procurement system? Run Step 1 in a loop, capture the returned id, then run Step 2 once per supporting document.

1. Create the vendor

   Your terminal — POST /v1/vendors with the vendor metadata. Only name is required; everything else can be filled in later via PATCH /v1/vendors/{vendorId}.

   Node.js

   const res = await fetch("https://api.vanta.com/v1/vendors", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: "Bearer YOUR_TOKEN",
     },
     body: JSON.stringify({
       name: "Acme Corp",
       websiteUrl: "https://acmecorp.com",
       category: "cloudStorage",
       servicesProvided: "Object storage and CDN",
       inherentRiskLevel: "MEDIUM",
     }),
   });
   const vendor = await res.json();
   console.log(vendor.id);
   

   Expected response (200) — the full vendor object, including the id you’ll need in Step 2:

   {
     "id": "a2f7e1b9d0c3f4e5a6c7b8d8",
     "name": "Acme Corp",
     "websiteUrl": "https://acmecorp.com",
     "category": { "displayName": "cloudStorage" },
     "status": "MANAGED",
     "inherentRiskLevel": "MEDIUM",
     "residualRiskLevel": null,
     "isVisibleToAuditors": true
   }
   

   Copy the id — you’ll send it as the path parameter in the next step.

   Got a 401?

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

   Setting category and custom risk attributes at the same time?

   The API processes the request in this order: (1) the category is applied, (2) all attributes inherited from that category are wiped, (3) the explicit attributes you sent are applied on top. This differs from the UI, which preserves both. Send the final, intended set of attributes in a single call.

   Need a security review?

   When the vendor’s inherentRiskLevel warrants it, Vanta automatically creates a security review. The review must be started from the Vendor page — there’s no API endpoint to start it.

2. Attach a document to the vendor

   Your terminal — POST /v1/vendors/{vendorId}/documents as multipart/form-data with the file in the file field and a document type (e.g. SOC2_REPORT, DPA, PRIVACY_POLICY, OTHER).

   Node.js

   import fs from "node:fs";
   
   const VENDOR_ID = "YOUR_VENDOR_ID";
   const FILE_PATH = "./acme-soc2.pdf";
   
   const form = new FormData();
   form.append(
     "file",
     new Blob([fs.readFileSync(FILE_PATH)], { type: "application/pdf" }),
     "acme-soc2.pdf",
   );
   form.append("type", "SOC2_REPORT");
   form.append("title", "Acme SOC 2 Type II – 2024");
   form.append("description", "Provided by Acme on 2024-09-01");
   
   const res = await fetch(
     `https://api.vanta.com/v1/vendors/${VENDOR_ID}/documents`,
     {
       method: "POST",
       headers: { Authorization: "Bearer YOUR_TOKEN" },
       body: form,
     },
   );
   console.log(await res.json());
   

   Expected response (200) — the uploaded document metadata:

   {
     "id": "a2f7e1b9d0c3f4e5a6c7b8d8",
     "title": "Acme SOC 2 Type II – 2024",
     "fileName": "acme-soc2.pdf",
     "type": "SOC2_REPORT",
     "mimeType": "application/pdf",
     "description": "Provided by Acme on 2024-09-01",
     "url": "https://example.com",
     "creationDate": "2024-09-01T00:00:00.000Z",
     "uploadedBy": { "id": "66993da0cf4ba2ad40599ba7", "type": "USER" }
   }
   

   Supported file types are .pdf, .docx, .jpg, .png, and .xlsx. You can’t attach a link as evidence via the API today — use the Vendor page for link evidence.

   Got a 404?

   The vendorId is wrong. Re-run Step 1 and copy the id exactly from the response (or from the URL on the Vendor page).

   Got a 415 or `Content-Type` error?

   The request must be multipart/form-data — don’t set Content-Type manually, let your HTTP client add the boundary. Pass the file with -F (curl), files= (requests), or a FormData body (fetch).

   Got a 400 on `type`?

   type is required and must be one of Vanta’s supported document types. Common values: SOC2_REPORT, ISO_27001_REPORT, PEN_TEST, DPA, PRIVACY_POLICY, OTHER. The full enum lives in the API reference.

Updating an existing vendor? Use PATCH /v1/vendors/{vendorId} with the same body shape (without name if you’re not changing it). To replace stale evidence, repeat Step 2 — each upload is stored independently and the latest is shown first.

Congratulations

You’ve added a vendor to your Vanta inventory and attached evidence to it. The vendor is now visible on your Vendor page, counts toward vendor-management tests, and the document is captured in your audit log.

Next steps

Sync custom vendor fields

Attach organization-specific metadata — contract dates, internal owners, risk tiers — to the vendor.

Assign a control owner

Make a specific user accountable for the vendor-management controls this evidence supports.

Try it in Postman

Import the collection and run createVendor + documents against a sandbox in seconds.

Manage Vanta API reference

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