Skip to main content
POST
/
api
/
lists
/
create-with-import
Preview a new-list import
curl --request POST \
  --url https://app.puffle.ai/api/lists/create-with-import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file": "<string>"
}
'
{ "columns": [ "<string>" ], "dataType": "people", "confidence": "high", "reasoning": "<string>", "personMapping": {}, "companyMapping": {}, "autoMapping": {}, "previewRows": [ {} ], "totalRows": 4503599627370495, "csvText": "<string>", "fileName": "<string>" }

​
Overview

Upload a CSV, XLS, or XLSX (multipart/form-data, field file, max 10 MB). The server parses the file, auto-detects whether it contains people or companies, and auto-maps columns for both data shapes (so the user can override detection in the UI). No list is created yet — call PUT /api/lists/create-with-import with the returned csvText + confirmed dataType + personMapping/companyMapping to actually create the list and import rows.
This operation shares the URL path /api/lists/create-with-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.

Body

application/json

Multipart/form-data. The preview step does not accept JSON — the confirm step (PUT) does.

​
file
string
required

CSV/XLS/XLSX file. Upload via multipart/form-data under field name file.

Response

Preview generated. Show the suggested mapping + data type to the user, then call the PUT to commit.

​
columns
string[]
required

Headers detected in the file.

​
dataType
enum<string>
required

Detected or declared data shape. people imports create list_rows plus inferred list_company_rows; companies imports create list_company_rows only.

Available options:
people,
companies
​
confidence
enum<string>
required

Confidence of the auto-detected data type.

Available options:
high,
medium,
low
​
reasoning
string
required

Human-readable explanation of the detected data type.

​
personMapping
object
required

Person-field mapping (only meaningful when dataType === 'people').

​
companyMapping
object
required

Company-field mapping (applies to both data types — populated for people imports too so the server can extract embedded company data).

​
autoMapping
object
required

Backward-compatibility alias. Equals companyMapping when dataType === 'companies', else personMapping.

​
previewRows
object[]
required

First 5 rows for UI preview.

​
totalRows
integer
required
Required range: 0 <= x <= 9007199254740991
​
csvText
string
required

Normalized CSV text. Pass this back verbatim in PUT /api/lists/create-with-import.

​
fileName
string
required

Original uploaded file name.