Import API Reference

Import Report

POST

POST /v1/import/{slug}

Submits a batch of records to the specified import report. Records are processed one at a time against the report’s field mapping and upserted on external_id. The response lists what each record created or updated.

Three things commonly cause a 404 or 422 here:

The path is /v1/import/{slug}: singular import, not imports. A request to /v1/imports/... returns a generic 404 Not Found, and a slug with no import report returns 422 with Invalid import slug.
The records must be wrapped under data: {"data": [ { ... } ]}. A bare record, or an empty list, returns 422.
The Import API requires a service-account API key. A dashboard session token is rejected with 401 Unauthorized role. See API keys.

Path parameters

string

required

The import report’s slug, shown as the endpoint on the report’s Configure tab.

Request body

The request body is a JSON object with a data key containing an array of records (or a single record object). 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"

slug = "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/{slug}",
    headers=headers,
    json=payload,
    timeout=30,
)
if resp.status_code == 422:
    detail = resp.json()["detail"]
    print(detail["message"] if isinstance(detail, dict) else detail)
    for error in (detail.get("errors", []) if isinstance(detail, dict) else []):
        print(error["record_index"], error.get("field"), error["error"])
else:
    resp.raise_for_status()
    result = resp.json()
    print(result["message"])
    for record in result["records"]:
        vendor = record["vendor"]
        print(record["record_index"], vendor["id"], "created" if vendor["created"] else "updated")

Example response

200 OK when every record succeeds:

{
  "success": true,
  "message": "Successfully imported 2 record(s)",
  "records_created": 2,
  "errors": null,
  "records": [
    {
      "record_index": 0,
      "vendor": { "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162", "external_id": "vendor-123", "created": false, "warnings": [] },
      "services": [],
      "engagements": [],
      "assessments": [],
      "findings": []
    },
    {
      "record_index": 1,
      "vendor": { "id": "cbvndr_9f4a1c0d7b2e4e9f8c1d2b3a4e5f6071", "external_id": "vendor-456", "created": true, "warnings": [] },
      "services": [],
      "engagements": [],
      "assessments": [],
      "findings": []
    }
  ]
}

Response fields

boolean

true on a 200 response.

string

A summary, such as Successfully imported 2 record(s).

integer

Number of records processed successfully, whether they created or updated objects.

object[]

One entry per successful record: its record_index (position in data), and the objects it created or updated under vendor, services, engagements, assessments, and findings. Each object carries id, external_id, created (true for a new object, false for an update), and warnings, such as an owner email that matched no user and was skipped.

object[] | null

Warnings that did not fail a record, such as a custom field sent as null, which is not written. null when there are none.

Errors

If any record fails, the response is 422. Records that succeeded are still saved, so fix the failed records and resend them; because records upsert on external_id, resending the whole batch is also safe. The detail object carries:

string

A summary, such as Imported 1 of 2 record(s) with 1 error(s).

integer

Number of records that succeeded.

integer

Number of records in the request.

object[]

One entry per failed record, with record_index, error (a readable message, for example Record missing required field External Id), field (the incoming field name at fault, when there is one), base_object (which object the field belongs to, in a report that imports several), and created (objects a multi-object record saved before it failed, or null).

object[]

The results for the records that succeeded, in the same shape as records above.

Other failures return 422 with a plain-string detail: a body that is not valid JSON or has no records (Invalid JSON: ...), or a slug with no import report (Invalid import slug).

Partial success is supported. Records that pass validation are imported even if other records in the same batch fail. The HTTP status is 200 only when every record succeeds.

Need help? Email support@coverbase.ai.

Getting started

API reference

Data import and export

Field reference

Integration workflows

AI, agents and MCP

Import Report

Path parameters

Request body

Example request

Example response

Response fields

Errors

​Import Report

​Path parameters

​Request body

​Example request

​Example response

​Response fields

​Errors

Import Report

Path parameters

Request body

Example request

Example response

Response fields

Errors