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.

​
Import Report

​
method
POST
POST /v1/import/{report_name}
Submits a batch of records to the specified import report. Records are validated against the report’s field mapping, upserted into the target base object using external_id, and returned with a per-record result summary.

​
Path parameters

​
report_name
string
required
The unique identifier of the import report.

​
Request body

The request body is a JSON object with a data key containing an array of records. Each record is an object whose keys are the mapped field names defined in the report and whose values are the incoming field values.
​
data
array
required
Records to import. Each record must include all fields marked as Required in the report’s mapping.

​
Example request

curl -X POST "https://api.coverbase.app/v1/import/vendor-custom-import" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "Name": "Acme Corporation",
        "External Id": "vendor-123",
        "Website": "https://acmecorp.com",
        "Status": "active",
        "Hq Location": "San Francisco, CA",
        "Raw Irq Score": "85"
      },
      {
        "Name": "Beta Services",
        "External Id": "vendor-456",
        "Website": "https://betaservices.io",
        "Status": "onboarding"
      }
    ]
  }'

​
Example response

{
  "id": "cbimprt_7b2c918fa4e14e6c9a3d7b21d4f8a0c2",
  "slug": "vendor-custom-import",
  "report_name": "Vendor Import",
  "base_object": "vendor",
  "mapping": {
    "name": "Name",
    "external_id": "External Id",
    "website": "Website",
    "status": "Status",
    "hq_location": "Hq Location",
    "raw_irq_score": "Raw Irq Score"
  },
  "received_count": 2,
  "created_count": 1,
  "updated_count": 1,
  "failed_count": 0,
  "results": [
    {
      "external_id": "vendor-123",
      "coverbase_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "action": "updated",
      "status": "success"
    },
    {
      "external_id": "vendor-456",
      "coverbase_id": "cbvndr_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071",
      "action": "created",
      "status": "success"
    }
  ],
  "errors": [],
  "received_at": 1745481600
}

​
Response fields

​
id
string
Unique Coverbase import report ID.
​
slug
string
Unique string used in the API endpoint URL.
​
report_name
string
Display name for the report.
​
base_object
string
The object each record in data represents (vendor, assessment, or service).
​
mapping
object
Mapping between Coverbase field names and the field names accepted in the incoming JSON objects.
​
received_count
integer
Total number of records received in the request body.
​
created_count
integer
Number of records that resulted in a new base object being created.
​
updated_count
integer
Number of records that matched an existing base object on external_id and were updated in place.
​
failed_count
integer
Number of records that were rejected due to validation or mapping errors.
​
results
array
Per-record result objects for successfully processed records. Each contains external_id, coverbase_id, action (created or updated), and status.
​
errors
array
Per-record error objects for rejected records. Each contains the record index, external_id (if available), error_code, and a human-readable message.
​
received_at
integer
Unix timestamp indicating when the import batch was received.

​
Error codes

CodeDescription
missing_required_fieldA required field (such as name or external_id) was absent from the record.
invalid_field_valueA field value failed type or format validation (for example, a malformed date or non-numeric score).
unmapped_fieldA field in the record is not defined in the report’s mapping and was ignored. Informational only; does not fail the record.
unknown_base_objectThe report’s configured base object is no longer valid.
duplicate_external_idThe same external_id appears more than once in a single request batch.
Partial success is supported. Records that pass validation are imported even if other records in the same batch fail. The HTTP response code is 200 when at least one record succeeds and 400 when all records fail validation.
Need help? Email support@coverbase.ai.