Import API Reference

Import Report

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.

Three things commonly cause a 404 or 422 here:

The path is /v1/import/{report_name}: singular import, not imports. A request to /v1/imports/... returns a generic 404 Not Found.
The body must be an array wrapped under data: {"data": [ { ... } ]}. A bare record object will not validate.
The Import API requires a service-account API key. See API keys.

Path parameters

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.

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

import os
import requests

API_KEY = os.getenv("COVERBASE_API_KEY", "<api-key>")
BASE_URL = "https://api.coverbase.app"

report_name = "vendor-custom-import"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "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",
        },
    ]
}

resp = requests.post(
    f"{BASE_URL}/v1/import/{report_name}",
    headers=headers,
    json=payload,
    timeout=30,
)
resp.raise_for_status()
result = resp.json()

print(f"Received: {result['received_count']}")
print(f"Created: {result['created_count']}, Updated: {result['updated_count']}, Failed: {result['failed_count']}")

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

string

Unique Coverbase import report ID.

string

Unique string used in the API endpoint URL.

string

Display name for the report.

string

The object each record in data maps to (vendor, assessment, or service).

object

Mapping between Coverbase field names and the field names accepted in the incoming JSON objects.

integer

Total number of records received in the request body.

integer

Number of records that resulted in a new base object being created.

integer

Number of records that matched an existing base object on external_id and were updated in place.

integer

Number of records that were rejected due to validation or mapping errors.

array

Per-record result objects for successfully processed records. Each contains external_id, coverbase_id, action (created or updated), and status.

array

Per-record error objects for rejected records. Each contains the record index, external_id (if available), error_code, and a human-readable message.

integer

Unix timestamp indicating when the import batch was received.

Error codes

Code	Description
`missing_required_field`	A required field (such as `name` or `external_id`) was absent from the record.
`invalid_field_value`	A field value failed type or format validation (for example, a malformed date or non-numeric score).
`unmapped_field`	A field in the record is not defined in the report’s mapping and was ignored. Informational only; does not fail the record.
`unknown_base_object`	The report’s configured base object is no longer valid.
`duplicate_external_id`	The 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.

Getting started

Products

Control Set library

Trust & security

API Reference

Data Import & Export

Reporting & Templates

Integration Workflows

AI, Agents, MCP

Import Report

Path parameters

Request body

Example request

Example response

Response fields

Error codes

​Import Report

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Error codes

Import Report

Path parameters

Request body

Example request

Example response

Response fields

Error codes