Copy the prompt to run this live via the MCP server or have AI generate a runnable script.
{children}
;
export const VENDORS_BUILD = "Using the Manage Vanta API (base URL https://api.vanta.com), write a Node.js script that creates a vendor and attaches an evidence file. The script should run on a recurring schedule (cron / GitHub Actions / Cloud Scheduler) so new vendors and refreshed evidence flow into Vanta automatically.\n\n1. Reads VANTA_CLIENT_ID, VANTA_CLIENT_SECRET, and VENDOR_INPUT_PATH from env (VENDOR_INPUT_PATH points to a JSON file with the vendor + evidence rows to apply). Fail fast if any are missing.\n2. Mints a Vanta API token using the client-credentials flow at POST https://api.vanta.com/oauth/token (Content-Type: application/json, body includes client_id, client_secret, grant_type=\"client_credentials\", scope=\"vanta-api.all:read vanta-api.all:write\"). Re-mint at the top of every run — tokens expire after one hour.\n3. For each row in the input file: a) check whether a vendor with that websiteUrl already exists by paging GET /v1/vendors with pageCursor pagination — if so, capture its id and skip creation. Otherwise create one with POST /v1/vendors. Body: { name, websiteUrl, category, servicesProvided, inherentRiskLevel }. Log the returned vendor id.\n4. Uploads an evidence file with POST /v1/vendors/{vendorId}/documents as multipart/form-data. Fields: file (binary), type (e.g. \"SOC2_REPORT\"), title, description. Do NOT set Content-Type manually — let the HTTP client inject the multipart boundary.\n5. Logs the returned document id and title.\n6. Persists a state file mapping websiteUrl → vendorId so re-runs are idempotent.\n7. Prints a JSON summary line: { \"created\": N, \"skipped\": S, \"uploaded\": U, \"errors\": E }.\n\nError handling:\n- 401: re-mint the token (expires after one hour) and retry once.\n- 415: warn that Content-Type must not be set manually for multipart uploads.\n- 400 on type field: log supported values — SOC2_REPORT, ISO_27001_REPORT, PEN_TEST, DPA, PRIVACY_POLICY, OTHER.\n- 5xx: retry with 2s exponential back-off, max 3 attempts.\n\nDo not hard-code any vendor name, websiteUrl, category, or file path — every customer's vendor list is different. Always read VENDOR_INPUT_PATH and discover existing vendors via /v1/vendors.\n\nAccepted file types: .pdf, .docx, .jpg, .png, .xlsx.\nScopes required: vanta-api.all:read, vanta-api.all:write.";
This guide creates a vendor in your Vanta vendor inventory with `POST /v1/vendors` and attaches an evidence file (SOC 2 report, DPA, pen test, security questionnaire) with `POST /v1/vendors/{vendorId}/documents` on the Manage Vanta API. The build prompt below generates a scheduled job that reads a vendor list from disk, deduplicates by `websiteUrl`, and uploads fresh evidence files idempotently.
## Before you begin
This guide is for Vanta admins managing data inside their own Vanta account.
You'll need:
* A Manage Vanta [API token](/docs/quickstart/manage-vanta).
* 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.
**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}`.
```javascript Node.js theme={"system"}
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);
```
```python Python theme={"system"}
import requests
r = requests.post(
"https://api.vanta.com/v1/vendors",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"name": "Acme Corp",
"websiteUrl": "https://acmecorp.com",
"category": "cloudStorage",
"servicesProvided": "Object storage and CDN",
"inherentRiskLevel": "MEDIUM",
},
)
r.raise_for_status()
print(r.json()["id"])
```
```bash Terminal theme={"system"}
curl -X POST 'https://api.vanta.com/v1/vendors' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
"name": "Acme Corp",
"websiteUrl": "https://acmecorp.com",
"category": "cloudStorage",
"servicesProvided": "Object storage and CDN",
"inherentRiskLevel": "MEDIUM"
}'
```
Expected response (`200`) — the full vendor object, including the `id` you'll need in Step 2:
```json theme={"system"}
{
"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.
Token is expired (one-hour lifetime), missing, or lacks `vanta-api.all:write`. Mint a fresh one — see [Authentication → Token expiration](/docs/concepts/authentication#token-expiration).
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.
When the vendor's `inherentRiskLevel` warrants it, Vanta automatically creates a security review. The review must be **started** from the [Vendor page](https://app.vanta.com/vendors) — there's no API endpoint to start it.
Security reviews are scoped per vendor — there is no top-level `GET /v1/security-reviews` endpoint. To enumerate every review, page through [`GET /v1/vendors`](/reference/manage-vanta/overview) and call [`GET /v1/vendors/{vendorId}/security-reviews`](/reference/manage-vanta/overview) for each vendor `id`.
Plan for the [50 requests/minute Manage Vanta rate limit](/reference/manage-vanta/overview#rate-limits): a tenant with several hundred vendors takes multiple minutes to fully enumerate. Cache the result, page with `pageSize=100` to minimize round trips, and re-fetch only the vendors whose `updatedAt` changed since the last run.
**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`).
```javascript Node.js theme={"system"}
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());
```
```python Python theme={"system"}
import requests
VENDOR_ID = "YOUR_VENDOR_ID"
FILE_PATH = "./acme-soc2.pdf"
with open(FILE_PATH, "rb") as f:
r = requests.post(
f"https://api.vanta.com/v1/vendors/{VENDOR_ID}/documents",
headers={"Authorization": "Bearer YOUR_TOKEN"},
files={"file": ("acme-soc2.pdf", f, "application/pdf")},
data={
"type": "SOC2_REPORT",
"title": "Acme SOC 2 Type II – 2024",
"description": "Provided by Acme on 2024-09-01",
},
)
r.raise_for_status()
print(r.json())
```
```bash Terminal theme={"system"}
VENDOR_ID="YOUR_VENDOR_ID"
curl -X POST "https://api.vanta.com/v1/vendors/$VENDOR_ID/documents" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-F 'file=@"./acme-soc2.pdf"' \
-F 'type="SOC2_REPORT"' \
-F 'title="Acme SOC 2 Type II – 2024"' \
-F 'description="Provided by Acme on 2024-09-01"'
```
Expected response (`200`) — the uploaded document metadata:
```json theme={"system"}
{
"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](https://app.vanta.com/vendors) for link evidence.
The `vendorId` is wrong. Re-run Step 1 and copy the `id` exactly from the response (or from the URL on the [Vendor page](https://app.vanta.com/vendors)).
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).
`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](/reference/manage-vanta/overview).
**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](https://app.vanta.com/vendors), counts toward vendor-management tests, and the document is captured in your audit log.
## Next steps
Attach organization-specific metadata — contract dates, internal owners, risk tiers — to the vendor.
Make a specific user accountable for the vendor-management controls this evidence supports.
Import the collection and run `createVendor` + `documents` against a sandbox in seconds.
Browse every Manage Vanta endpoint — vendors, controls, tests, documents, people.