CoherenceCOHERENCE

Import & Export API

Planned API for bulk import from CSV/Excel files and export to CSV or PDF

Planned — not yet available. This page describes a planned capability. The endpoints below do not exist yet and may change before release. Today, CSV/Excel import and export are available inside the Coherence app, and for programmatic bulk writes you can use the live Records API bulk endpoints.

The planned Import & Export API will bring the app's bulk data workflows to the public API: importing records from external files and exporting data in multiple formats.

Planned Import Flow

Imports will follow a four-step workflow so nothing is committed until you've reviewed it:

  1. Parse — upload a CSV or Excel file and get a column/row preview
  2. Map — map source columns to module fields, with optional AI suggestions
  3. Validate — check the mapped data for errors before importing
  4. Execute — run the import with configurable duplicate handling

Import endpoint sketch (design preview)

MethodEndpointPurpose
POST/modules/{module}/import/parseUpload and parse a file
POST/modules/{module}/import/suggest-mappingAI column-mapping suggestions
POST/modules/{module}/import/validateValidate mapped data
POST/modules/{module}/import/executeExecute the import
GET/modules/{module}/import/jobs/{jobId}Job status / progress
DELETE/modules/{module}/import/jobs/{jobId}Roll back an import

Example (design preview)

Executing an import will look like:

curl -X POST "https://api.getcoherence.io/v1/modules/contacts/import/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [...],
    "columnMapping": [
      {"sourceColumn": "Name", "targetFieldSlug": "displayName"},
      {"sourceColumn": "Email", "targetFieldSlug": "email"}
    ],
    "duplicateStrategy": "update",
    "duplicateMatchFields": ["email"]
  }'

and will return a job summary:

{
  "importJob": {
    "id": "job_abc123",
    "status": "completed",
    "successRows": 1498,
    "errorRows": 2,
    "skippedRows": 50
  }
}

Planned duplicate handling

StrategyBehavior
skipSkip rows that match existing records
updateUpdate matched records with imported values
createAlways create new records (allows duplicates)

Large files will process asynchronously — the job endpoint will report progress, and completed imports will be reversible via rollback (which will permanently delete the records the import created).

Planned Export Flow

Exports will produce CSV or PDF from any module, synchronously for small datasets and via async jobs for large ones.

Export endpoint sketch (design preview)

MethodEndpointPurpose
POST/modules/{module}/exportExport module records
GET/export-jobs/{exportJobId}Async export job status

Export requests will accept a format (csv or pdf) plus options such as column selection, header labels, sort, and a record limit. Small exports will return the file directly; large exports will return a job whose result is a time-limited download URL.

Errors

Planned endpoints will use the standard Coherence error envelope (see Error Handling):

{
  "error": {
    "message": "Unsupported file type",
    "statusCode": 400
  }
}

Related: API Overview | Records API | Authentication