Vendors & Services API - Coverbase Docs

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.

object[]

Values your organization has set on this service. Empty array if none are set, and always empty on a create response. See the Custom Fields API.

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.

boolean

default:"false"

Populate custom_fields on each row. Off by default so listing stays cheap; single-vendor reads always include them. See the Custom Fields API.

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, custom_fields, created_at, and updated_at. (No services or personnel arrays; see the note above.) custom_fields is empty unless you pass include_custom_fields=true.

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,
      "custom_fields": [],
      "created_at": 1746576000
    }
  ],
  "custom_fields": [
    {
      "config_id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d",
      "field_name": "Exception Status",
      "field_type": "select",
      "value": "Open"
    }
  ],
  "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.

object[]

Values your organization has set on this vendor. Empty array if none are set. See the Custom Fields API for the value shapes. Nested services carry their own custom_fields.

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,
    "financial_health": {
      "scorecard": {
        "score": 68,
        "band": "moderate",
        "confidence_tier": "C",
        "as_of": "2026-08-12",
        "pillars": [
          {
            "pillar": "capital_position",
            "score": 50,
            "weight": 0.25,
            "contributions": [
              {
                "label_key": "current_ratio",
                "score": 62,
                "weight": 0.5,
                "value": 1.82,
                "unit": "ratio",
                "detail_key": null,
                "peer_ranked": true,
                "as_of": "2026-03-31"
              },
              {
                "label_key": "registration_status",
                "score": 50,
                "weight": 0.5,
                "value": null,
                "unit": "categorical",
                "detail_key": "unknown",
                "peer_ranked": false,
                "as_of": null
              }
            ]
          }
        ],
        "provenance": { "edgar": "2026-03-31" },
        "unavailable_sources": ["pitchbook"]
      },
      "history": [{ "as_of": "2026-05-12", "score": 65, "band": "moderate" }]
    }
  },
  "people": { "leadership": [{ "name": "Jordan Lee", "title": "CEO" }] },
  "compliance_legal": { "legal_actions": [] },
  "security_posture": {
    "trust_center_url": "https://trust.supplier1.example.com",
    "security_incidents": [],
    "external_intelligence": {
      "domain": "supplier1.example.com",
      "generated_at": 1746575800,
      "overall_score": 84,
      "overall_grade": "B",
      "predictive_index": 12,
      "factor_scores": [
        {
          "factor": "email_security",
          "score": 45,
          "grade": "F",
          "data_available": true,
          "weight": 0.12,
          "findings": [
            {
              "code": "dmarc_policy_none",
              "severity": "high",
              "subject": "supplier1.example.com",
              "detail": "p=none",
              "penalty": 25,
              "first_seen": "2026-01-04",
              "last_seen": "2026-08-12"
            },
            {
              "code": "dkim_weak_key",
              "severity": "moderate",
              "subject": "selector1",
              "detail": "1024-bit",
              "penalty": 15,
              "first_seen": "2026-08-12",
              "last_seen": "2026-08-12"
            }
          ]
        },
        {
          "factor": "tls_configuration",
          "score": 100,
          "grade": "A",
          "data_available": false,
          "weight": 0.1,
          "findings": []
        }
      ]
    }
  }
}

Branch on data_available before you read score. The second factor in that example was not measured on this run (the probe reached no conclusion), so it was excluded from overall_score entirely. But it still serializes as score: 100, grade: "A", with its normal weight, because a factor that took no deductions starts at 100.An integration that renders factor_scores without checking data_available will show an unmeasured factor as a perfect one. Treat data_available: false as “no data”, regardless of what score, grade, and weight say.

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.). Includes registry_validation, the validated corporate identity, with a citation per contributing register. 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. Includes financial_health (the Coverbase Financial Health Score) when your organization has that feature enabled. 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. Includes external_intelligence (the measured outside-in security rating) when your organization has that feature enabled. 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.

Vendor intelligence sections

Three sections carry outside-in intelligence measured from registries of record and from the vendor’s own infrastructure, rather than produced by a language model. All three cite their sources. See Vendor Intelligence, Financial Health Score, and Security Intelligence for what each field means.

The Financial Health Score and the measured security rating are optional features in beta, enabled per organization. Write your integration to treat financials.financial_health and security_posture.external_intelligence as optional: both are null for an organization that does not have them enabled, and a section can be null even when status is "completed".

object | null

Validated corporate identity from GLEIF, OpenCorporates, and SEC EDGAR: official_name, registration_status, jurisdiction, incorporation_date, addresses, and the identifiers lei, duns, company_number, and cik. is_validated is true only when a register matched with high confidence; match_decision and match_confidence expose the match quality. sources carries one entry per contributing register with its identifier and a url to the record.Present for every organization. null until a lookup has run.

object | null

The Coverbase Financial Health Score. scorecard holds score (0-100), band (very_high through very_low), confidence_tier (A, B, or C), as_of, the pillars breakdown, vitals, peer_group and peer_percentile, events, overrides_applied, provenance (source → as-of date), and unavailable_sources. history carries prior scores for trend.Returned only when your organization has the Financial Health Score enabled; null otherwise.

object[]

The individual inputs behind a pillar score, ordered by weighted shortfall so the input that cost the most comes first. Each entry carries:

label_key: the feature identifier (for example operating_margin, registration_status), or the adverse-event type
score: what this input scored, 0-100
weight: how heavily it counted within the pillar
value and unit: the measured figure and its unit (percent, ratio, months, years, usd, days_overdue, or categorical)
detail_key: the category behind a non-numeric input (unknown, dissolved, down). When this is present, value is not a measurement. A score of 50 with detail_key: "unknown" means the input could not be determined, not that it was measured as mediocre, so render the two cases differently
peer_ranked: false means the score came from an absolute curve rather than a peer percentile. This is the single most important caveat on any individual number
as_of: the date this input’s value was true, which is not the date of the refresh

label_key and detail_key are open sets: new identifiers appear as sources are added, so map unknown keys to a readable fallback rather than failing.

Scores are only directly comparable within the same confidence_tier. Tier A is computed from filed financial statements; Tier C is inferred from funding, headcount, and corporate-standing signals. Do not rank vendors across tiers on score alone.

object | null

The measured outside-in security rating, assembled by querying the vendor’s own public infrastructure. Top-level fields: domain (the domain that was rated), generated_at (unix timestamp), overall_score (0-100), overall_grade (A through F), predictive_index (0-100 likelihood of imminent exploitation), factor_scores, and the raw evidence blocks: vulnerability_findings, exposed_services, breach_exposures, email_authentication, web_headers, tls_certificate, dns_health, web_reputation.Returned only when your organization has the measured security rating enabled; null otherwise.

object[]

One entry per scored factor. factor is one of patching_cadence, network_security, email_security, tls_configuration, web_application_headers, dns_health, leaked_information, ip_reputation, application_security, web_reputation, domain_squatting. score is 0-100, grade is A through F, and weight is the absolute weight the factor carried in overall_score.data_available is the field to branch on, and the one most likely to bite an integration. When it is false, the factor could not be measured on this run and was excluded from overall_score, but it still carries score: 100, grade: "A", and its normal weight, because a factor that took no deductions never left its starting value. Read data_available first and treat false as “no data”; rendering or alerting on score without that check turns an unmeasured factor into a perfect one.Only factors that were actually scored appear in the array. An organization without the measured security rating enabled gets the seven original factors and no entries for email_security, tls_configuration, web_application_headers, or domain_squatting at all.findings carries the structured evidence (below); drivers carries the same evidence pre-rendered as English sentences, intended for prompt context rather than display.

object[]

The observed facts behind a factor’s score, structured so they can be localized:

code: the finding identifier, which selects the sentence (dmarc_policy_none, dkim_weak_key, hsts_missing, cookie_not_secure, …)
severity: critical, high, moderate, low, or info
subject: what the finding is about, such as a host, a DKIM selector, a cookie name, or a CVE
detail: the observed value, rendered verbatim in every locale (p=none, 1024-bit, TLSv1.0)
penalty: points this finding cost its factor
evidence_url: a link to the record, where one exists
first_seen / last_seen: ISO-8601 dates carried across refreshes. first_seen is how long the finding has stood open, which is often more informative than the finding itself

code is an open set and grows as probes are added. Map an unrecognized code to subject and detail, which are always human-readable, rather than dropping the finding.

A clean overall_grade is not evidence of good internal security. Every input is visible from outside the vendor’s perimeter and says nothing about access control, key management, secure development, or incident response. Use it to prioritize, not to certify.

Enabling the measured security rating changes overall_score for existing vendors: the rating goes from seven factors to eleven, with new weights. If you store or alert on overall_score, expect a one-time shift when the feature is turned on for your organization.

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

​Vendor intelligence sections

​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

Vendor intelligence sections

Error responses

Refresh a vendor’s fact sheet

Path parameters

Example request

Example response

Error responses