Skip to main content
For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
The Import API is the ingestion counterpart to the Export API. It allows secure, programmatic delivery of vendor, service, engagement, assessment, and finding data into Coverbase from upstream systems of record.

​
What you can do

Sync vendor inventory

Mirror your ERP, procurement system, or internal CMDB into Coverbase so procurement and risk share one source of truth.

Migrate from legacy GRC

Bulk-load historical assessment data when cutting over from a legacy TPRM platform or spreadsheets.

Push service catalogs

Keep third-party service mappings current by piping data from engineering or architecture catalogs.

Bridge intake and CLM

Connect intake forms, ticketing, and contract lifecycle tools into the Coverbase vendor graph without manual re-entry.
The API uses a RESTful design with a predictable URL structure and communicates entirely in JSON. All interactions are authenticated with an API key and encrypted in transit.

​
Setup

The Import API requires you to first create an import report in the dashboard: open Configuration → Coverbase API, switch to the Import API tab, and click New Import Report. The report defines what records create or update, the field mapping between your incoming payload and Coverbase fields, and the POST endpoint used to submit records. Its Configure tab shows the endpoint and a sample payload; its Request history tab lists every request that reached the endpoint, with the request and response bodies. To configure the report, you pick one or more objects under Import data into. When you POST to the endpoint, the request body contains a JSON array of records under the data key, each using the field names you mapped. Calls must use an ak_ API key.

​
Base objects

Every object upserts on external_id, the stable identifier from your source system: a record whose external_id matches an existing object of that type updates it in place instead of creating a duplicate. Objects that belong to another object name their parent by its external_id (vendor_external_id, assessment_external_id, service_external_id), so import parents first. Any mapped field that is not a standard field is treated as a custom field, and that custom field must already exist in your workspace.

​
Vendor

Imports create or update vendor records in the Coverbase vendor inventory. Each record must include name and external_id. The payload also supports website, displayed_website, description, hq_location, status (a status label), use_case, products, tags (a list of {"key": ..., "value": ...} objects), the raw inherent and residual risk scores (raw_irq_score, raw_residual_risk_score), risk_domain_scores, next_assessment_date, last_assessment_date, security_contact_email, trust_center_url, contact_personnel, and people by email (relationship_owner_emails, risk_analyst_emails, watcher_emails). An email that matches no user is skipped with a warning. A vendor imported with a last_assessment_date and no next_assessment_date is put on your organization’s reassessment cadence counted from that date. Example: Syncing the full list of active suppliers from your ERP nightly so that Coverbase’s vendor inventory reflects procurement’s source of truth without manual entry.

​
Assessment

Imports create or update assessment records linked to a vendor. Each record must include external_id and vendor_external_id. The payload also supports name, assignee_email, products, risk_type, status (a status label), the raw inherent and residual risk scores, recommendation, approval_option (an approval option label), an assessment plan (assessment_plan_id or assessment_plan_name, applied only when the assessment is created), and service_external_id to link one of the vendor’s services. Example: Migrating three years of completed SIG Lite and CAIQ assessments from a legacy GRC platform so that vendor history is preserved when customers cut over to Coverbase.

​
Service

Imports create or update service records representing the specific third-party services a vendor provides. A single vendor can have multiple services, each with its own risk profile. Each record must include external_id, name, and vendor_external_id. The payload also supports description, status, the raw inherent and residual risk scores, risk_domain_scores, next_assessment_date, tags, contact_personnel, relationship_owner_emails, and watcher_emails. Example: Loading a service catalog that distinguishes “Acme Corp, Payments API” from “Acme Corp, Cloud Hosting” so that assessments and monitoring events are scoped to the specific service consumed rather than the vendor as a whole.

​
Finding

Imports create or update findings. Each record must include external_id, title, and exactly one of vendor_external_id or assessment_external_id. The payload also supports description, status, due_date, assignee_email, watcher_emails, and severity, urgency, and risk_level as level names from your finding scales. An unknown level name is skipped with a warning.

​
Engagement

Imports create or update engagements under a vendor. Each record must include external_id, name, and vendor_external_id. The payload also supports description, status, start_date, end_date, the raw inherent and residual risk scores, risk_domain_scores, tags, contact_personnel, relationship_owner_emails (with relationship_owner_first_name and relationship_owner_last_name for a single owner), and service_external_ids, which replaces the engagement’s service links. An unknown service external_id rejects the record.

​
Several objects in one record

Select more than one object under Import data into to make a composite report. Each record then carries one key per object (vendor, service or services, engagement or engagements, assessment or assessments, finding or findings), each mapped separately, so one record can create a vendor together with its services, engagements, assessments, and findings. The objects in a record are saved one by one: if a later object fails, the ones before it stay saved and the error lists them.

​
Field mapping

Each import report defines a mapping from incoming field names in your payload to the corresponding Coverbase fields on the object. The dashboard exposes all available target fields for the selected objects and marks which ones are Required.
Fields in a record that the mapping does not name are ignored. A record missing a required field is rejected, and the response lists it with the field that was missing.
Changing the mapping takes effect on the next request, without changing the endpoint URL or your client code.

​
Request format

All requests are POST to the report endpoint with a JSON body of the shape:
A single record can also be sent as an object under data. Records are processed one at a time, and each record that succeeds is saved even when another record in the same request fails. Because every object upserts on external_id, resending a request is safe. See the Import API reference for the response.