Import CSV (optimized) - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

The response confirms admission only; counts are initially null. Poll import status with task_id, or poll operation status with operation_run_id (jobs:read). These are different IDs. The endpoint always queues a durable Runtime v2 import; it has no synchronous mode.

field_mappings is a JSON object keyed by CSV header. Values may be a destination field string (for example {"Email":"email"}), {"type":"standard","field":"email"}, {"type":"custom","name":"source_email"}, or {"type":"skip"}. Standard targets must be writable manual/source columns or supported canonical import fields; reserved/calculated/system fields cannot be written. Whether custom targets can create a new manual column depends on the table's existing writable columns. The import validates mappings before the worker writes rows. If the optional ingest_policy is invalid, the server ignores it and uses the table's ingest defaults.

Recommended safe flow

Validate CSV parse/shape with Validate CSV import.
Import via this endpoint; admission is asynchronous.
Poll Get CSV import status until terminal.
Run Verify CSV import by task.
If needed, use Rollback CSV import by task.

Blacklist controls

check_company_blacklist defaults to true.
check_email_blacklist defaults to false.
Rows skipped by blacklist checks are reported in blacklist_summary.
Add/manage entries with Create blacklist entry and related blacklist endpoints.
Recommended workflow only: before separate billable enrichment operations (llm_enrichment, email finder, phone finder), use a blacklist filter gate. This is not an additional admission requirement enforced by the CSV import endpoint.

Long fields like post_content are supported when multiline values are properly CSV-quoted. Rollback deletes manifest-tracked rows created by this import; it does not restore rows updated by upsert or rows skipped by blacklist/identity handling.

Path parameters

table_idrequired
string
Target table ID.

Name	Type	Description
table_idrequired	string	Target table ID.

Body parameters

null_policy · optional
string: common | preserve
Default common maps blank values and recognized null tokens to empty strings; preserve retains nonblank null-token text. Blank values still normalize to empty.
ingest_policy · optional
string (JSON)
Optional IngestPolicy JSON object controlling identity handling. Invalid JSON or policy values are ignored and table defaults apply.
command_center_context · optional
string (JSON)
Optional existing Command Center operation context. Standalone API integrations can omit it; do not invent thread identifiers.
filerequired
multipart file
CSV file upload.
field_mappings · optional
string (JSON)
Optional JSON object serialized as a multipart field. Map each CSV header to a destination field name, such as {"Email":"email"}; standard/custom/skip mapping objects are also accepted.
check_company_blacklist · optional
boolean
Defaults to true.
check_email_blacklist · optional
boolean
Defaults to false.
origin · optional
string
Origin tag for created columns/rows. Default: csv.

Name	Type	Description
null_policy	string: common \| preserve	Default common maps blank values and recognized null tokens to empty strings; preserve retains nonblank null-token text. Blank values still normalize to empty.
ingest_policy	string (JSON)	Optional IngestPolicy JSON object controlling identity handling. Invalid JSON or policy values are ignored and table defaults apply.
command_center_context	string (JSON)	Optional existing Command Center operation context. Standalone API integrations can omit it; do not invent thread identifiers.
filerequired	multipart file	CSV file upload.
field_mappings	string (JSON)	Optional JSON object serialized as a multipart field. Map each CSV header to a destination field name, such as {"Email":"email"}; standard/custom/skip mapping objects are also accepted.
check_company_blacklist	boolean	Defaults to true.
check_email_blacklist	boolean	Defaults to false.
origin	string	Origin tag for created columns/rows. Default: csv.

Definitions

IngestPolicy

Serialize this object as the ingest_policy multipart field. Omit it to use the table ingest defaults.

Fields

mode · optional
string
allow (default), skip, or upsert.
rule_id · optional
string
ID of an existing identity rule on the table.
column_key · optional
string
Explicit identity column, used with match_strategy when rule_id is absent.
match_strategy · optional
string
domain, email, linkedin_url, external_id, or exact_text.
merge_mode · optional
string
fill_empty (default) or overwrite_mapped.

Name	Type	Description
mode	string	allow (default), skip, or upsert.
rule_id	string	ID of an existing identity rule on the table.
column_key	string	Explicit identity column, used with match_strategy when rule_id is absent.
match_strategy	string	domain, email, linkedin_url, external_id, or exact_text.
merge_mode	string	fill_empty (default) or overwrite_mapped.

Errors

Status	Meaning
400	Invalid CSV or multipart payload.
401	Invalid API key or missing auth.
403	Missing tables:write scope or table access denied.
409	For scheduled imports, the uploaded artifact does not match the admitted artifact.
422	Missing required multipart file or invalid null_policy value.
503	CSV upload storage or admission receipt could not be completed.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/67bd8c39c7d3e80f0a95b560/import-optimized" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -F "file=@contacts.csv" \
    -F "check_company_blacklist=true" \
    -F "check_email_blacklist=false" \
    -F 'field_mappings={"Email":"email"}'

Request body

json

(multipart/form-data request)

Response example

json

{
    "status": "processing",
    "task_id": "7f1e0d4f-6b6e-44ff-9fd2-03f2f7ebad85",
    "operation_run_id": "operation-run-example",
    "message": "CSV import queued",
    "row_count": null,
    "column_count": null
  }