Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.vanta.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide writes organization-specific metadata — contract dates, internal owners, risk tiers, ticket links — to vendors using PATCH /v1/vendors/{vendorId} with a customFields payload on the Manage Vanta API. Custom field labels must be defined in the Vanta vendor settings UI first; the API only fills in their values. The build prompt below generates a scheduled job that syncs a CSV export from a procurement or GRC system into Vanta, only PATCHing vendors whose fields actually changed.

​
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 custom fields you want to set must be defined ahead of time in the Vanta UI (the API can only fill custom fields, not create them).
Custom fields let you attach organization-specific metadata to vendors — contract end dates, internal owners, risk ratings, or anything else you track. They’re defined in the Vendor settings page by name and type, then set or updated via the API.
Importing a backlog of vendors from your procurement system? Define every custom field you’ll send first in the Vendor settings page, then run Step 1 in a loop. Field names sent in the API must match the Vanta-side label exactly — including case, and values must match the field’s type:
  • String → JSON string: "value": "Tier 1"
  • Number → JSON number: "value": 10
  • Date → ISO 8601 string: "value": "2026-01-01T00:00:00.000Z"
  • Boolean → JSON bool: "value": true
1

Set custom fields when creating a vendor

Your terminal — POST /v1/vendors with a customFields array. Each entry has label (matches the Vanta-side field name) and value (matches the field’s type).
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",
    customFields: [
      { label: "contractEndDate", value: "2026-01-01T00:00:00.000Z" },
      { label: "internalRiskTier", value: "Tier 2" },
    ],
  }),
});
const vendor = await res.json();
console.log(vendor.id);
Expected response (200) — the full vendor object, including the values you just set:
{
  "id": "a2f7e1b9d0c3f4e5a6c7b8d8",
  "name": "Acme Corp",
  "category": { "displayName": "cloudStorage" },
  "customFields": [
    { "label": "contractEndDate", "value": "2026-01-01T00:00:00.000Z" },
    { "label": "internalRiskTier", "value": "Tier 2" }
  ]
}
The label doesn’t match a defined custom field. Check the Vendor settings page — labels are case-sensitive and must match exactly.
Your JSON value doesn’t match the custom field’s type. A Date field needs an ISO 8601 string; a Number needs a JSON number, not a string; a Boolean needs true/false, not "true"/"false".
2

Update custom fields on an existing vendor

Your terminal — PATCH /v1/vendors/{vendorId} with the same customFields shape. Only the fields you send are changed; omitted fields keep their current values.
const VENDOR_ID = "YOUR_VENDOR_ID";

const res = await fetch(`https://api.vanta.com/v1/vendors/${VENDOR_ID}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_TOKEN",
  },
  body: JSON.stringify({
    customFields: [
      { label: "contractEndDate", value: "2027-01-01T00:00:00.000Z" },
    ],
  }),
});
console.log(await res.json());
A 200 response returns the updated vendor with its new customFields.
Sending customFields with category in the same call wipes any category-derived risk attributes before applying your custom values — see the Create a vendor guide for the ordering rules.
The vendorId is wrong. Re-run GET /v1/vendors and copy the id exactly, or grab it from the URL on the Vendor page.
Send the field with value: null. The label still has to match a defined field.
Bulk-syncing from a procurement system? List vendors with GET /v1/vendors, match each one to your source-of-truth record by name or websiteUrl, then run Step 2 per vendor with the latest custom-field values. Tokens expire hourly — re-mint at the top of each run.

​
Congratulations

You’ve populated organization-specific metadata on your vendors. Custom field values are visible on each vendor’s profile, queryable via the API, and included in vendor exports for auditors.

​
Next steps

Create a vendor and attach evidence

Set up a new vendor end-to-end with metadata, custom fields, and a SOC 2 report.

Assign a control owner

Make a specific user accountable for vendor-management controls.

Try it in Postman

Import the collection and run vendor POST and PATCH against a sandbox in seconds.

Manage Vanta API reference

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