​
Overview

The Import API provides a multi-step workflow for importing data into boards from CSV files. The process follows four stages: upload, column mapping, preview, and execution. This ensures data integrity by letting users review and correct mappings before committing changes.

​
Upload CSV

Upload a CSV file and receive a parsed column/row summary.

POST /api/trpc/import.uploadCsv

Request: multipart/form-data

FieldTypeRequiredDescription
fileFileYesCSV file (max 10 MB, UTF-8)
boardIdstringYesTarget board ID
delimiterstringNoColumn delimiter (default: auto-detect)

Response:

{
  "result": {
    "data": {
      "json": {
        "importId": "imp_01HXK5QJBN3YZXM8KJP2RSNV4C",
        "fileName": "items-export.csv",
        "fileSize": 45230,
        "delimiter": ",",
        "encoding": "utf-8",
        "totalRows": 156,
        "columns": [
          { "index": 0, "header": "Task Name", "sampleValues": ["Fix login bug", "Update docs", "Review PR"] },
          { "index": 1, "header": "Status", "sampleValues": ["Open", "Done", "In Progress"] },
          { "index": 2, "header": "Assigned To", "sampleValues": ["Alice", "Bob", "Charlie"] },
          { "index": 3, "header": "Due Date", "sampleValues": ["2026-04-01", "2026-03-28", "2026-04-10"] },
          { "index": 4, "header": "Priority", "sampleValues": ["High", "Low", "Medium"] }
        ],
        "expiresAt": "2026-03-23T11:00:00.000Z"
      }
    }
  }
}

Uploaded files are stored temporarily and expire after 1 hour. Complete the import workflow before expiry or re-upload the file.

​
Map Columns

Define how CSV columns map to board columns.

POST /api/trpc/import.mapColumns

{
  "json": {
    "importId": "imp_01HXK5...",
    "mappings": [
      { "csvIndex": 0, "target": "item_name" },
      { "csvIndex": 1, "target": "column", "columnId": "col_01HXK5..." },
      { "csvIndex": 2, "target": "column", "columnId": "col_01HXK6..." },
      { "csvIndex": 3, "target": "column", "columnId": "col_01HXK7..." },
      { "csvIndex": 4, "target": "column", "columnId": "col_01HXK8..." }
    ],
    "groupId": "grp_01HXK5...",
    "skipFirstRow": true,
    "dateFormat": "YYYY-MM-DD"
  }
}
FieldTypeRequiredDescription
importIdstringYesImport session ID from upload step
mappingsarrayYesColumn mapping definitions
mappings[].csvIndexnumberYesCSV column index (0-based)
mappings[].targetstringYesitem_name, column, group, or skip
mappings[].columnIdstringConditionalBoard column ID (required when target is column)
groupIdstringNoDefault group for imported items
skipFirstRowbooleanNoSkip header row (default: true)
dateFormatstringNoDate parsing format (default: YYYY-MM-DD)

​
Preview Import

Preview the import result without committing. Shows how rows will be mapped and any validation errors.

POST /api/trpc/import.preview

{
  "json": {
    "importId": "imp_01HXK5..."
  }
}

Response:

{
  "result": {
    "data": {
      "json": {
        "importId": "imp_01HXK5...",
        "totalRows": 156,
        "validRows": 152,
        "errorRows": 4,
        "preview": [
          {
            "row": 2,
            "itemName": "Fix login bug",
            "values": {
              "col_01HXK5...": { "parsed": "Open", "valid": true },
              "col_01HXK6...": { "parsed": "Alice Johnson", "valid": true, "resolvedUserId": "usr_01HXK5..." },
              "col_01HXK7...": { "parsed": "2026-04-01", "valid": true },
              "col_01HXK8...": { "parsed": "High", "valid": true }
            }
          }
        ],
        "errors": [
          { "row": 45, "column": "Due Date", "value": "next week", "error": "Invalid date format" },
          { "row": 89, "column": "Assigned To", "value": "Unknown User", "error": "User not found in organization" }
        ]
      }
    }
  }
}

Review the errors array carefully before executing. Rows with errors will be skipped during execution unless corrected.

​
Execute Import

Commit the import and create items on the board.

POST /api/trpc/import.execute

{
  "json": {
    "importId": "imp_01HXK5...",
    "skipErrorRows": true
  }
}
FieldTypeRequiredDescription
importIdstringYesImport session ID
skipErrorRowsbooleanNoSkip rows with validation errors (default: true)

Response:

{
  "result": {
    "data": {
      "json": {
        "importId": "imp_01HXK5...",
        "status": "completed",
        "itemsCreated": 152,
        "itemsSkipped": 4,
        "duration": 2340,
        "boardId": "brd_01HXK5..."
      }
    }
  }
}

​
Get Import History

List past imports for a board.

GET /api/trpc/import.getHistory?input={"json":{"boardId":"brd_01HXK5..."}}

Response:

{
  "result": {
    "data": {
      "json": {
        "imports": [
          {
            "id": "imp_01HXK5...",
            "fileName": "items-export.csv",
            "status": "completed",
            "totalRows": 156,
            "itemsCreated": 152,
            "itemsSkipped": 4,
            "importedBy": { "id": "usr_01HXK5...", "name": "Alice Johnson" },
            "completedAt": "2026-03-23T10:05:00.000Z"
          }
        ]
      }
    }
  }
}

Import history is retained for 90 days. Use it to audit data lineage and troubleshoot duplicate imports.

Was this page helpful?

Embeds APIPDF Export