Preview a CSV Mapping

Parse the stashed CSV’s headers + a sample and return auto-detected column suggestions and the assignable fields for the mapping UI.

POST /contacts/import/preview

Contact Import Preview

cURL

curl --request POST \
  --url https://api.example.com/contacts/import/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "s3_key": "<string>"
}
'

200

{}

Second step of the CSV import flow. Reads the stashed object back (ranged GET, capped at 15 MB — 413 if the actual object is larger than declared), parses headers + the first 5 data rows, and auto-suggests a canonical field for each CSV column by header name (e.g. "Work Email" → email). Nothing is written yet.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Field	Type	Description
columns	array of {header, suggested}	One entry per CSV column. suggested is a canonical field key (email, first_name, last_name, phone, title, department, company, company_domain, linkedin_url, tags, notes) or null if no alias matched.
fields	array of {key, label, type_hint, identity}	The canonical fields a CSV column can be mapped to. identity: true on email, first_name, last_name, linkedin_url — a row needs at least one of these mapped-and-populated to import.
sample	array of object	Up to 5 raw data rows, keyed by original CSV header.
total_rows	integer	Total data rows in the file (not just the sample).

Errors

Status	Cause
400	s3_key isn’t under the caller’s import prefix.
413	Object exceeds 15 MB.
422	Empty file, or missing a header row.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Parse a stashed CSV's headers + a sample for the mapping UI.

s3_key · string · required

The s3_key returned by upload-init.

Minimum string length: 1

Response

200

application/json

Successful Response

The response is of type Response Contact Import Preview Contacts Import Preview Post · object.