Set custom fields on vendors

Attach organization-specific metadata — contract dates, internal owners, risk tiers, anything you track — to vendors when creating or updating them, 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 custom fields you want to set 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, then run Step 2 in a loop. Field names sent in the API must match the Vanta-side label exactly — including case.

1. Define the custom field in Vanta

   Vanta dashboard — open the Vendor settings page, add the custom field you want to use, and pick its type (String, Number, Date, Boolean, etc.).

   Note the label and type exactly — the API will reject any value whose label doesn’t match an existing custom field, or whose value doesn’t match the field’s type.

   Field types and what to send

   • 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

   Why can't I create custom fields via API?

   Custom field definitions are an org-wide schema change — they affect every vendor and every UI surface — so they’re intentionally UI-only. The API is for populating values.

2. 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).

   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",
       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" }
     ]
   }
   

   Got a 400 saying the custom field doesn't exist?

   The label doesn’t match a defined custom field. Check the Vendor settings page — labels are case-sensitive and must match exactly.

   Got a 400 saying the value type is wrong?

   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".

3. 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.

   Node.js

   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.

   Got a 404?

   The vendorId is wrong. Re-run GET /v1/vendors and copy the id exactly, or grab it from the URL on the Vendor page.

   Need to clear a custom field?

   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 3 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.