Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coverbase.com/llms.txt

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

The Vendors API lets external systems read and update individual vendor records. To create or bulk-update vendors, use the Import API instead. The most common use of this API is lifecycle transitions: signaling that a vendor is offboarding, suspending a vendor pending review, or unblocking a procurement record once an assessment completes.

​
Retrieve a vendor

​
method
GET
GET /v1/vendors/{vendor_id}
Returns the full profile of a single vendor.

​
Path parameters

​
vendor_id
string
required
The Coverbase vendor ID (cbvndr_...).

​
Example request

cURL
curl -X GET "https://api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -H "Authorization: Bearer <api-key>"

​
Example response

{
  "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "external_id": "ariba-req-7821",
  "name": "Acme Corporation",
  "website": "https://acmecorp.com",
  "description": "Enterprise customer support tooling provider",
  "hq_location": "San Francisco, CA",
  "status": {
    "id": "cbsts_a1b2c3d4e5f6",
    "label": "Active",
    "group": "started"
  },
  "tags": [
    { "id": "cbtag_f1e2d3c4b5a6", "name": "processes_pii" },
    { "id": "cbtag_a9b8c7d6e5f4", "name": "saas" }
  ],
  "risk_analyst_ids": ["cbusr_a1b2c3d4..."],
  "relationship_owner_ids": ["cbusr_e5f6a7b8..."],
  "inherent_risk_level_id": "cbscl_7a8b9c0d1e2f",
  "residual_risk_level_id": "cbscl_3f4e5d6c7b8a",
  "raw_irq_score": 0.72,
  "engagement_type": "saas_platform",
  "use_case": "Customer support ticketing",
  "next_assessment_date": 1754352000,
  "last_assessment_outcome": "approved_with_findings",
  "created_at": 1732292930,
  "updated_at": 1746575800
}

​
Response fields

​
id
string
The Coverbase vendor ID.
​
external_id
string or null
External system identifier (e.g., an Ariba request ID) if one was provided during import.
​
name
string
Vendor name.
​
website
string or null
Vendor website URL.
​
description
string or null
Vendor description.
​
hq_location
string or null
Headquarters location.
​
status
object
The vendor’s current status as a CbStatus object with id, label, and group fields. The group is one of unstarted, started, completed, or canceled.
​
tags
array
Array of tag objects, each with id and name fields.
​
risk_analyst_ids
array
User IDs of assigned risk analysts.
​
relationship_owner_ids
array
User IDs of relationship owners.
​
inherent_risk_level_id
string or null
ID of the scale level representing inherent risk.
​
residual_risk_level_id
string or null
ID of the scale level representing residual risk.
​
raw_irq_score
float or null
Raw IRQ (Inherent Risk Questionnaire) score.
​
engagement_type
string or null
Type of engagement with this vendor.
​
use_case
string or null
How the vendor is used within the organization.
​
next_assessment_date
integer or null
Unix timestamp of the next scheduled assessment.
​
last_assessment_outcome
string or null
Outcome of the most recent assessment.
​
created_at
integer
Unix timestamp when the vendor record was created.
​
updated_at
integer
Unix timestamp of the last update.

​
Update a vendor

​
method
PATCH
PATCH /v1/vendors/{vendor_id}
Updates one or more fields on an existing vendor. Most commonly used to transition lifecycle state. Updates fire vendor.updated and, if status changes, vendor.status_changed webhooks.

​
Updatable fields

​
status_id
string
ID of a CbStatus record to transition to. Must be a valid, non-archived vendor status for the org.
​
name
string
Vendor name.
​
website
string or null
Vendor website URL. Send an empty string to clear.
​
description
string or null
Vendor description.
​
hq_location
string or null
Headquarters location.
​
risk_analyst_ids
array
Replace the entire set of risk analyst user IDs.
​
relationship_owner_ids
array
Replace the entire set of relationship owner user IDs.
​
tag_ids
array
Replace the entire tag set using CbTag IDs.
​
inherent_risk_level_id
string or null
Scale level ID for inherent risk.
​
residual_risk_level_id
string or null
Scale level ID for residual risk.
​
raw_irq_score
float or null
Raw IRQ score value.
​
next_assessment_date
integer or null
Unix timestamp of the next scheduled assessment.
​
use_case
string or null
How the vendor is used within the organization.
​
engagement_type
string or null
Type of engagement with this vendor.
​
custom_field_data
array
Array of custom field value objects for org-specific fields.

​
Example request

curl -X PATCH "https://api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "cbsts_offboarding_7f8e9d0c",
    "use_case": "Legacy system — winding down"
  }'

​
Example response

{
  "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "external_id": "ariba-req-7821",
  "name": "Acme Corporation",
  "status": {
    "id": "cbsts_offboarding_7f8e9d0c",
    "label": "Offboarding",
    "group": "started"
  },
  "use_case": "Legacy system — winding down",
  "updated_at": 1746576400
}
This update fires both vendor.updated and vendor.status_changed webhooks. Any workflow bound to those events will run, for example the offboarding sequence described in Workflow C: Vendor offboarding.

​
Vendor statuses

Vendor statuses are org-customizable. Each status belongs to a group (unstarted, started, completed, canceled). Use the dashboard or a list statuses endpoint to see available statuses for your org. Any valid, non-archived vendor status ID can be set via status_id. Status transitions are not enforced — you can move a vendor to any status that exists for your org.
Statuses are CbStatus records with target_type=VENDOR. Each org defines their own status labels, colors, and groups. If you need to discover available statuses programmatically, query the statuses list endpoint filtered by target type.

​
Error responses

StatusCodeWhen
400invalid_status_idThe provided status_id doesn’t exist, is archived, or isn’t a vendor status for this org.
400missing_required_fieldA required field was omitted.
404vendor_not_foundThe provided vendor_id does not exist or is not accessible to the API key.