Vendors & Services API - Coverbase API

A vendor (cbvndr_...) is a parent supplier entity. A service (cbsvc_...) is a child entity under a vendor. This API creates and reads both. All endpoints are org-scoped to the API key. See API conventions for authentication, IDs, timestamps, idempotency, and the error envelope.

To upload, version, and search bills of materials (SBOM, AIBOM, HBOM, SaaSBOM) for a vendor or service, see the Bill of Materials API.

To upload evidence documents (SOC 2 reports, policies, contracts, questionnaires) for a vendor and link them to its services and assessments, see the Documents API.

Method	Path	Idempotent
`POST`	`/v1/vendors`	Yes (`Idempotency-Key`)
`GET`	`/v1/vendors`	—
`GET`	`/v1/vendors/{vendor_id}`	—
`PATCH`	`/v1/vendors/{vendor_id}`	No
`POST`	`/v1/vendors/{vendor_id}/services`	No
`PATCH`	`/v1/vendors/{vendor_id}/services/{service_id}`	No
`GET`	`/v1/vendors/{vendor_id}/fact-sheet`	—
`POST`	`/v1/vendors/{vendor_id}/fact-sheet/refresh`	No

The primary contact object

Both vendor and service endpoints accept/return a primary_contact. On a vendor it is the address the inherent-risk-questionnaire portal invite (and other vendor emails) are sent to; on a service it is the service-level point-of-contact.

Field	Type	Notes
`email`	string	Required, validated as an email address.
`name`	string \| null	Contact name.
`title`	string \| null	Contact title.
`phone_number`	string \| null	Contact phone.

On read, primary_contact is derived from the stored contact personnel (first entry with an email) — for vendors it falls back to the vendor’s security contact email. It is null if no contact is set.

Assigning people (analysts, owners, watchers)

Vendors and services accept optional personnel assignments as arrays of user IDs (cbuser_...). All are optional; on create, omit them to assign no one. On update (PATCH), supplying an array replaces the existing set — pass [] to clear it, or omit the field to leave it unchanged.

Field	Vendor	Service	Meaning
`risk_analyst_ids`	✓	—	Risk analysts. Vendor-only — services do not have risk analysts.
`relationship_owner_ids`	✓	✓	Relationship owners.
`watcher_ids`	✓	✓	Watchers (users who follow the vendor/service for notifications).

These fields take Coverbase user IDs, not emails. Syncing from an external system (e.g. ServiceNow) that keys on email? Use the Users API to resolve an email to its cbuser_... ID — GET /v1/users?email= looks one up, and POST /v1/users provisions the user if they don’t exist yet (returning the existing user if they do).

Create a vendor

POST

POST /v1/vendors

Creates a parent vendor. Returns 201 Created with the full vendor object.

Request body

string

required

Vendor name.

string

Vendor website URL.

string

Vendor description.

string

Headquarters location.

string

How the vendor is used within the organization.

string

Your system’s identifier for this vendor (e.g. an Ariba request ID). Stored and echoed back; useful for correlation.

string[]

Risk analyst user IDs (cbuser_...) to assign. See assigning people.

string[]

Relationship owner user IDs (cbuser_...) to assign.

string[]

Watcher user IDs (cbuser_...) to assign.

object

The vendor point-of-contact (see the primary contact object). If supplied, email is required and validated.

Headers

string

required

Bearer ak_...

string

Optional. Replaying the same key within 24 hours returns the original 201 body. See Idempotency.

Example request

curl -X POST "https://sandbox.api.coverbase.app/v1/vendors" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Idempotency-Key: acme-vendor-test1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME_Sup_Test1",
    "website": "https://supplier1.example.com",
    "use_case": "Demo supplier for Acme Inc sandbox",
    "external_id": "ariba-req-7821"
  }'

import os
import requests

API_KEY = os.environ["COVERBASE_API_KEY"]
BASE_URL = "https://sandbox.api.coverbase.app"

resp = requests.post(
    f"{BASE_URL}/v1/vendors",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "acme-vendor-test1",
        "Content-Type": "application/json",
    },
    json={
        "name": "ACME_Sup_Test1",
        "website": "https://supplier1.example.com",
        "use_case": "Demo supplier for Acme Inc sandbox",
        "external_id": "ariba-req-7821",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Example response

201 Created — the full vendor object (see response fields below):

{
  "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "external_id": "ariba-req-7821",
  "name": "ACME_Sup_Test1",
  "website": "https://supplier1.example.com",
  "description": null,
  "hq_location": null,
  "status": null,
  "status_id": null,
  "tags": [],
  "risk_analyst_ids": [],
  "relationship_owner_ids": [],
  "watcher_ids": [],
  "inherent_risk_level_id": null,
  "residual_risk_level_id": null,
  "engagement_type": null,
  "use_case": "Demo supplier for Acme Inc sandbox",
  "tier": null,
  "primary_contact": null,
  "services": [],
  "created_at": 1746576000,
  "updated_at": 1746576000
}

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_vendor", "message": "..."}}`	Creation rejected by a business rule.
422	Standard validation error	`name` missing, body malformed, or `primary_contact.email` not a valid email.

Create a child service

POST

POST /v1/vendors/{vendor_id}/services

Creates a service under an existing vendor. Returns 201 Created.

This endpoint does not honor Idempotency-Key — sending the header is harmless but has no effect. Retrying after a successful create makes a second service.

Path parameters

string

required

The parent vendor ID (cbvndr_...).

Request body

string

required

Service name.

string

Service description.

string

Your system’s identifier for this service.

string[]

Tag IDs (cbtag_...) to attach to the service.

string[]

Relationship owner user IDs (cbuser_...) to assign. See assigning people.

string[]

Watcher user IDs (cbuser_...) to assign.

object

The service point-of-contact (see the primary contact object). If supplied, email is required and validated.

Services do not have risk analysts — risk analysts are assigned on the parent vendor. Sending risk_analyst_ids to a service endpoint has no effect.

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162/services" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME_Sup_Test1 — Primary Service",
    "relationship_owner_ids": ["cbuser_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"],
    "watcher_ids": ["cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"],
    "primary_contact": { "email": "service-owner@supplier1.example.com" }
  }'

Example response

201 Created (see the service object):

{
  "id": "cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "name": "ACME_Sup_Test1 — Primary Service",
  "description": null,
  "external_id": null,
  "tags": [],
  "relationship_owner_ids": ["cbuser_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"],
  "watcher_ids": ["cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"],
  "primary_contact": { "email": "service-owner@supplier1.example.com", "name": null, "title": null, "phone_number": null },
  "created_at": 1746576000
}

Service object

string

Service ID (cbsvc_...).

string

The parent vendor ID.

string

Service name.

string | null

Service description.

string | null

Your external identifier, if supplied.

string[]

Tag value strings (empty array if none).

string[]

Relationship owner user IDs (cbuser_...). Empty array if none.

string[]

Watcher user IDs (cbuser_...). Empty array if none.

object | null

The service point-of-contact (see the primary contact object), or null.

integer

Unix timestamp (seconds).

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_service", "message": "..."}}`	Creation rejected by a business rule.
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` does not exist or is not in the API key’s org.
422	Standard validation error	`name` missing or body malformed.

Update a service

PATCH

PATCH /v1/vendors/{vendor_id}/services/{service_id}

Updates a service. Only included fields change. Returns the updated service object.

Path parameters

string

required

The parent vendor ID (cbvndr_...).

string

required

The service ID (cbsvc_...). Must belong to vendor_id.

Request body

string

Service name.

string

Service description.

string[]

Replace the service’s tag set (tag IDs cbtag_...).

string[]

Replace the relationship owner set (user IDs cbuser_...). Pass [] to clear.

string[]

Replace the watcher set (user IDs cbuser_...). Pass [] to clear.

object

Replace the service point-of-contact (see the primary contact object). When supplied, email is required and validated.

external_id is set only at creation and is not updatable here. Services do not have risk analysts.

Example request

cURL

curl -X PATCH "https://sandbox.api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162/services/cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME_Sup_Test1 — Renamed Service" }'

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_service", "message": "..."}}`	Update rejected by a business rule.
404	`{"detail": {"code": "service_not_found", "message": "Service not found."}}`	The service does not exist, or does not belong to `vendor_id`, or is not in the API key’s org.
422	Standard validation error	Body failed schema validation.

List vendors

GET

GET /v1/vendors

Lists vendors in the API key’s org, newest first. Without filters it returns every vendor, paginated. Use it to enumerate vendors, resolve a vendor by name, or map your own identifier to a Coverbase vendor ID.

List rows are a lightweight summary — they omit the nested services and the personnel-assignment arrays. Fetch GET /v1/vendors/{vendor_id} for the full object.

Query parameters

string

Case-insensitive substring match on the vendor (or service) name.

string

Exact match on the vendor’s external_id — handy for mapping your system’s identifier back to a Coverbase vendor.

integer

default:"50"

Page size, 1–200.

integer

default:"0"

Number of rows to skip, for pagination.

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/vendors?name=acme&limit=50" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK:

{
  "items": [
    {
      "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "external_id": "ariba-req-7821",
      "name": "ACME_Sup_Test1",
      "website": "https://supplier1.example.com",
      "description": null,
      "hq_location": null,
      "status": "Active",
      "status_id": "cbst_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "tags": ["saas"],
      "use_case": "Customer support ticketing",
      "tier": "tier_2",
      "primary_contact": null,
      "created_at": 1732292930,
      "updated_at": 1746575800
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

object[]

The page of vendor summaries. Each carries id, external_id, name, website, description, hq_location, status, status_id, tags, use_case, tier, primary_contact, created_at, and updated_at. (No services or personnel arrays — see the note above.)

integer

Total vendors matching the filters (across all pages).

integer

The page size used.

integer

The offset used.

Retrieve a vendor

GET

GET /v1/vendors/{vendor_id}

Path parameters

string

required

The vendor ID (cbvndr_...).

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "external_id": "ariba-req-7821",
  "name": "ACME_Sup_Test1",
  "website": "https://supplier1.example.com",
  "description": "Enterprise customer support tooling provider",
  "hq_location": "San Francisco, CA",
  "status": "Active",
  "status_id": "cbst_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "tags": ["processes_pii", "saas"],
  "risk_analyst_ids": ["cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"],
  "relationship_owner_ids": ["cbuser_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"],
  "watcher_ids": ["cbuser_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"],
  "inherent_risk_level_id": "cbsclvl_7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
  "residual_risk_level_id": "cbsclvl_3f4e5d6c7b8a9b0c1d2e3f4a5b6c7d8e",
  "engagement_type": "saas_platform",
  "use_case": "Customer support ticketing",
  "tier": "tier_2",
  "primary_contact": {
    "email": "security@supplier1.example.com",
    "name": "Jordan Lee",
    "title": "CISO",
    "phone_number": "+1-555-0100"
  },
  "services": [
    {
      "id": "cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab",
      "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "name": "ACME_Sup_Test1 — Primary Service",
      "description": null,
      "external_id": null,
      "tags": [],
      "relationship_owner_ids": [],
      "watcher_ids": [],
      "primary_contact": null,
      "created_at": 1746576000
    }
  ],
  "created_at": 1732292930,
  "updated_at": 1746575800
}

Vendor object

string

Vendor ID (cbvndr_...).

string | null

Your external identifier, if set.

string

Vendor name.

string | null

Vendor website URL.

string | null

Vendor description.

string | null

Headquarters location.

string | null

Current status as a plain label string (e.g. "Active"). Org-customizable. null if unset.

string | null

ID (cbst_...) of the current status record.

string[]

Tag value strings (empty array if none).

string[]

Assigned risk analyst user IDs (cbuser_...).

string[]

Relationship owner user IDs (cbuser_...).

string[]

Watcher user IDs (cbuser_...).

string | null

Scale level ID (cbsclvl_...) for inherent risk.

string | null

Scale level ID (cbsclvl_...) for residual risk.

string | null

Type of engagement with this vendor.

string | null

How the vendor is used.

string | null

Derived vendor tier (e.g. tier_1, tier_2). Set by workflow tiering actions; null until derived.

object | null

The vendor point-of-contact (see the primary contact object), or null.

object[]

The vendor’s child services, each a service object. Empty array if none.

integer

Unix timestamp (seconds) of creation.

integer

Unix timestamp (seconds) of last update.

Error responses

Status	Body	When
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` does not exist or is not in the API key’s org.

Update a vendor

PATCH

PATCH /v1/vendors/{vendor_id}

Updates one or more fields. Only included fields change; omitted fields are untouched. The full, refreshed vendor object is returned.

Every body field is optional. Sending null for a field is treated the same as omitting it (no change) — there is no clear-to-null behavior.

Request body

string

Vendor name.

string

Vendor website URL.

string

Vendor description.

string

Headquarters location.

string

ID (cbst_...) of a status record to transition to.

string[]

Replace the entire tag set, using tag IDs (cbtag_...).

string[]

Replace the risk analyst set (user IDs cbuser_...). Pass [] to clear.

string[]

Replace the relationship owner set (user IDs cbuser_...). Pass [] to clear.

string[]

Replace the watcher set (user IDs cbuser_...). Pass [] to clear.

string

Scale level ID (cbsclvl_...) for inherent risk.

string

Scale level ID (cbsclvl_...) for residual risk.

string

How the vendor is used.

string

Type of engagement.

object

Replace the vendor point-of-contact (see the primary contact object). When supplied, email is required and validated.

external_id and tier are not updatable through this endpoint (external_id is set only at creation; tier is derived by workflows).

Example request

cURL

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

The response is the full vendor object (same shape as Retrieve a vendor).

Error responses

Status	Body	When
400	`{"detail": {"code": "invalid_update", "message": "..."}}`	Update rejected (e.g. an invalid reference ID).
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` not found / not in org.
422	Standard validation error	Body failed schema validation.

The vendor fact sheet

The fact sheet is AI-generated company intelligence about a vendor — company profile, products, public perception, financials, leadership, compliance/legal posture, and security posture. Coverbase assembles it from public sources; in the dashboard it powers the vendor “Fact Sheet” tab and its PDF export. These two endpoints let you read that data and trigger a regeneration programmatically. Generation is asynchronous. Trigger it with the refresh endpoint, then poll the fact sheet endpoint until status is "completed".

`status`	Meaning
`null`	Never generated. Call the refresh endpoint to populate it.
`"pending"`	Generation is in progress.
`"completed"`	The most recent generation run finished successfully.
`"failed"`	The most recent generation run failed. Trigger another refresh to retry.

Retrieve a vendor’s fact sheet

GET

GET /v1/vendors/{vendor_id}/fact-sheet

Returns the current fact sheet for a vendor. A vendor that has never had a fact sheet generated returns 200 with status: null and every section null — it is not a 404.

Path parameters

string

required

The vendor ID (cbvndr_...).

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162/fact-sheet" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK:

{
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "entity_id": "cbentity_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "status": "completed",
  "progress": ["company profile", "products", "security posture"],
  "generated_at": 1746575800,
  "company_profile": {
    "name": "ACME_Sup_Test1",
    "website": "https://supplier1.example.com",
    "industry": "Customer support software",
    "hq_location": "San Francisco, CA",
    "founded_year": 2014,
    "description": "Enterprise customer support tooling provider"
  },
  "products": { "products": [{ "name": "Helpdesk", "description": "Ticketing platform" }] },
  "public_perception": { "news_mentions": [], "competitors": [] },
  "financials": { "public_private": "private", "market_cap_usd": null },
  "people": { "leadership": [{ "name": "Jordan Lee", "title": "CEO" }] },
  "compliance_legal": { "legal_actions": [] },
  "security_posture": { "trust_center_url": "https://trust.supplier1.example.com", "security_incidents": [] }
}

Fact sheet object

string

The vendor ID (cbvndr_...).

string | null

ID of the underlying entity that holds the fact sheet data. null if the vendor is not yet linked to an entity.

string | null

Generation status — null, "pending", "completed", or "failed" (see the status table above).

string[]

Section names completed so far in the in-progress / most recent run. Empty array if none.

integer | null

Unix timestamp (seconds) the fact sheet was last updated. null if never generated.

object | null

Company profile (name, website, industry, HQ, founding year, headcount, revenue, etc.). null until generated.

object | null

Known products and offerings. null until generated.

object | null

News mentions, third-party reviews (BBB, Trustpilot, CFPB), and competitors. null until generated.

object | null

Public/private status, market cap, ticker/exchange, funding, and transactions. null until generated.

object | null

Leadership and headcount estimate. null until generated.

object | null

Legal actions, enforcement actions, and data-privacy certifications. null until generated.

object | null

Trust center URL, security contact, and known security incidents. null until generated.

Section objects are best-effort and their internal shape may evolve as Coverbase improves enrichment. Treat the presence of each field defensively; any individual section can be null even when status is "completed" if no data was found for it.

Error responses

Status	Body	When
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` does not exist or is not in the API key’s org.

Refresh a vendor’s fact sheet

POST

POST /v1/vendors/{vendor_id}/fact-sheet/refresh

Queues a (re)generation of the vendor’s fact sheet and returns immediately with 202 Accepted and status: "pending". Existing fact sheet data is cleared at the start of the run, so a GET made right after a refresh reflects the pending state. Poll the fact sheet endpoint until status is "completed".

This endpoint is not idempotent — each call queues a fresh generation run.

Path parameters

string

required

The vendor ID (cbvndr_...).

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/vendors/cbvndr_e448ba62882143f3ba0c140bb2e30162/fact-sheet/refresh" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

202 Accepted:

{
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "entity_id": "cbentity_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "status": "pending",
  "message": "Fact sheet regeneration has been queued."
}

string

The vendor ID (cbvndr_...).

string | null

ID of the underlying entity, or null when the vendor is being linked to one for the first time as part of this run.

string

Always "pending" on a successful enqueue.

string

Human-readable acknowledgement.

Error responses

Status	Body	When
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` does not exist or is not in the API key’s org.

​The primary contact object

​Assigning people (analysts, owners, watchers)

​Create a vendor

​Request body

​Headers

​Example request

​Example response

​Error responses

​Create a child service

​Path parameters

​Request body

​Example request

​Example response

​Service object

​Error responses

​Update a service

​Path parameters

​Request body

​Example request

​Error responses

​List vendors

​Query parameters

​Example request

​Example response

​Retrieve a vendor

​Path parameters

​Example request

​Example response

​Vendor object

​Error responses

​Update a vendor

​Request body

​Example request

​Error responses

​The vendor fact sheet

​Retrieve a vendor’s fact sheet

​Path parameters

​Example request

​Example response

​Fact sheet object

​Error responses

​Refresh a vendor’s fact sheet

​Path parameters

​Example request

​Example response

​Error responses

The primary contact object

Assigning people (analysts, owners, watchers)

Create a vendor

Request body

Headers

Example request

Example response

Error responses

Create a child service

Path parameters

Request body

Example request

Example response

Service object

Error responses

Update a service

Path parameters

Request body

Example request

Error responses

List vendors

Query parameters

Example request

Example response

Retrieve a vendor

Path parameters

Example request

Example response

Vendor object

Error responses

Update a vendor

Request body

Example request

Error responses

The vendor fact sheet

Retrieve a vendor’s fact sheet

Path parameters

Example request

Example response

Fact sheet object

Error responses

Refresh a vendor’s fact sheet

Path parameters

Example request

Example response

Error responses