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/{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

method

POST

POST /v1/vendors

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

Request body

name

string

required

Vendor name.

website

string

Vendor website URL.

description

string

Vendor description.

hq_location

string

Headquarters location.

use_case

string

How the vendor is used within the organization.

external_id

string

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

risk_analyst_ids

string[]

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

relationship_owner_ids

string[]

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

watcher_ids

string[]

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

primary_contact

object

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

Headers

Authorization

string

required

Bearer ak_...

Idempotency-Key

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"
  }'

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

method

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

vendor_id

string

required

The parent vendor ID (cbvndr_...).

Request body

name

string

required

Service name.

description

string

Service description.

external_id

string

Your system’s identifier for this service.

tag_ids

string[]

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

relationship_owner_ids

string[]

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

watcher_ids

string[]

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

primary_contact

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

vendor_id

string

The parent vendor ID.

name

string

Service name.

description

string | null

Service description.

external_id

string | null

Your external identifier, if supplied.

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

method

PATCH

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

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

Path parameters

vendor_id

string

required

The parent vendor ID (cbvndr_...).

service_id

string

required

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

Request body

name

string

Service name.

description

string

Service description.

tag_ids

string[]

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

relationship_owner_ids

string[]

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

watcher_ids

string[]

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

primary_contact

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.

Retrieve a vendor

method

GET

GET /v1/vendors/{vendor_id}

Path parameters

vendor_id

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

external_id

string | null

Your external identifier, if set.

name

string

Vendor name.

website

string | null

Vendor website URL.

description

string | null

Vendor description.

hq_location

string | null

Headquarters location.

status

string | null

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

status_id

string | null

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

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

method

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

name

string

Vendor name.

website

string

Vendor website URL.

description

string

Vendor description.

hq_location

string

Headquarters location.

status_id

string

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

tag_ids

string[]

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

risk_analyst_ids

string[]

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

relationship_owner_ids

string[]

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

watcher_ids

string[]

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

inherent_risk_level_id

string

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

residual_risk_level_id

string

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

use_case

string

How the vendor is used.

engagement_type

string

Type of engagement.

primary_contact

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

method

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

vendor_id

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

vendor_id

string

The vendor ID (cbvndr_...).

entity_id

string | null

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

status

string | null

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

progress

string[]

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

generated_at

integer | null

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

company_profile

object | null

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

products

object | null

Known products and offerings. null until generated.

public_perception

object | null

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

financials

object | null

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

people

object | null

Leadership and headcount estimate. null until generated.

compliance_legal

object | null

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

security_posture

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

method

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

vendor_id

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

vendor_id

string

The vendor ID (cbvndr_...).

entity_id

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.

status

string

Always "pending" on a successful enqueue.

message

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

​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

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