Preview a table CSV import

Upload a CSV to preview headers, up to five sample rows, protected/generated columns, suggested mappings, detected types, and importable existing table columns. This endpoint does not import or mutate table rows.

POST/api/tables/{table_id}/csv-preview

HTTP referenceScope tables:writeUpdated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

Developer API keys need the listed scope. A valid authenticated user session may also call this route.

Mapping analysis can fall back to basic unmapped-column suggestions when the AI mapping service is unavailable. Only the first five rows are returned as sample_rows. Consult the workspace column catalog for valid table fields; the dynamic response example is abbreviated.

Path parameters

table_idrequired
string
Research table identifier; caller must have access.

Name	Type	Description
table_idrequired	string	Research table identifier; caller must have access.

Body parameters

filerequired
file<text/csv>
CSV uploaded as multipart form data.
null_policy · optional
string
common treats configured common null tokens as empty; preserve retains input values.

Name	Type	Description
filerequired	file<text/csv>	CSV uploaded as multipart form data.
null_policy	string	common treats configured common null tokens as empty; preserve retains input values.

Errors

Status	Meaning
401	Authentication is missing or invalid.
403	The credential is invalid or lacks the required scope, or the caller cannot access the resource.
400	The CSV is empty or could not be parsed.
422	Request validation failed, including a missing required file or invalid multipart/form value.
500	An unexpected preview-processing error occurred.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/table-id/csv-preview" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -F "file=@./companies.csv" \
  -F "null_policy=common"

Response example

json

{
  "headers": [
    "Company",
    "Domain"
  ],
  "active_headers": [
    "Company",
    "Domain"
  ],
  "skipped_generated_columns": [],
  "sample_rows": [
    {
      "Company": "Example Co",
      "Domain": "example.test"
    }
  ],
  "field_mappings": [
    {
      "csv_column": "Domain",
      "table_column": "domain",
      "confidence": 0.96
    }
  ],
  "unmapped_columns": [],
  "detected_types": {
    "Company": "text",
    "Domain": "url"
  },
  "data_quality": {
    "has_email": false,
    "has_names": false,
    "has_company": true,
    "primary_key_suggestion": null
  },
  "existing_columns": [
    {
      "key": "domain",
      "label": "Domain",
      "data_type": "url"
    }
  ]
}