Skip to main content
POST
Preview a CSV or Excel import into a list.

Authorizations

X-API-Key
string
header
required

Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard.

Path Parameters

listId
string
required

Body

application/json

The CSV or Excel file to preview

Request body for previewing a CSV or Excel import into a list. Send a CSV or Excel file (.csv, .xlsx, .xls) as multipart file, or name one saved in a project with projectId and path (files uploaded to a chat are saved under /uploads/ in the chat's project). For a workbook, sheet picks the sheet; the first sheet is the default.

projectId
string

Project (UUID) holding the file. Use with path instead of uploading a file.

path
string

Path of the file in the project, e.g. "/uploads/contacts.csv".

sheet
string

Workbook sheet to read. Defaults to the first sheet; ignored for CSV.

companyId
string

Company ID that owns the list. Required when authenticating with a personal access key (pak_…) — the key is not tied to a specific company so the server cannot infer it. Required when authenticating with a company API key only if the key belongs to a user who has access to multiple companies; otherwise it defaults to the key's company. Optional for JWT (dashboard) auth — defaults to the user's active company.

Response

File columns, sample rows and the suggested mapping

The file's columns, its first rows, and the suggested column mapping.

headers
string[]

File column names.

headerMapping
object

Suggested mapping: file column name -> existing list column id, or "new".

existingHeaders
object[]

The list's current columns (id, name, type).

preview
object[]

The first 4 rows, keyed by column name.

rowCount
integer

Number of rows in the file (the chosen sheet, for a workbook).

sheets
string[]

Sheet names, for a workbook. Pass one as sheet to read it instead of the first.

status
string

Always "success".