Skip to main content
POST
/
api
/
lists
/
{id}
/
import
Preview a CSV/XLSX import into an existing list
curl --request POST \
  --url https://app.puffle.ai/api/lists/{id}/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file": "<string>"
}
'
{ "columns": [ "<string>" ], "auto_mapping": {}, "preview_rows": [ {} ], "total_rows": 4503599627370495, "csv_text": "<string>", "existing_columns": [ "<string>" ] }

​
Overview

Upload a CSV, XLS, or XLSX file (multipart/form-data, field file, max 10 MB). The server parses headers, auto-detects column mappings (pattern match + optional LLM for unmapped fields + custom-column matching), and returns a preview payload. No rows are inserted yet — call PUT /api/lists/{id}/import with the returned csv_text and the finalized mapping to actually write.
This operation shares the URL path /api/lists/{id}/import with other verbs. See the sibling page for related operations on the same resource.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

List UUID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

Multipart/form-data. This endpoint does NOT accept JSON — upload the file under the file form field.

​
file
string
required

The CSV/XLS/XLSX file to preview. Sent as multipart/form-data with field name file, not JSON.

Response

File parsed and column mapping suggested. No rows written yet.

​
columns
string[]
required

Column headers detected in the uploaded file.

​
auto_mapping
object
required

AI/pattern-detected mapping of CSV column names onto built-in fields (first_name, last_name, full_name, linkedin_url, headline, company, location, domain). Unmapped CSV columns are surfaced as column:<Name> (existing custom column) or new:<Name> (propose to create).

​
preview_rows
object[]
required

First 5 parsed rows keyed by column header for preview.

​
total_rows
integer
required

Total data rows detected in the file.

Required range: 0 <= x <= 9007199254740991
​
csv_text
string
required

Normalized CSV text. Pass this back verbatim in PUT /api/lists/{id}/import as csv_text.

​
existing_columns
string[]
required

Names of existing custom columns on the target list.