Skip to main content
POST
Import CSV or Excel rows 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 import and its column mapping

Request body for importing CSV or Excel rows 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. Imports over 100 rows run in the background and respond 202 with a taskId. Only one file import runs per list at a time (409 otherwise).

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.

headerMapping
object

Maps each file column name to the id of an existing list column, "new" to add it as a new column, or "ignore" to skip it. Get the suggested mapping from lists_importPreview. When omitted, the suggested mapping is used. In multipart requests, send it as a JSON string.

Response

Import finished (200) or started in the background (202)

Result of a file import: "background" with a taskId (202) for imports over 100 rows, otherwise msg "Success" (200) once the rows are imported.

status
string

"background" when the import runs asynchronously.

taskId
string

Background task ID (UUID). Poll it with lists_getTaskStatus until status is "completed", "failed", or "cancelled".

message
string

Human-readable status message.

rowCount
integer

Number of rows being imported.

msg
string

"Success" when a small import finished immediately.