Skip to main content
POST
Create a new smart list.

Authorizations

X-API-Key
string
header
required

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

Body

application/json

List data

Request body for creating a new smart list. Sharing visibility is controlled by listDict.sharing — see field description for the three modes.

listDict
object
required

List properties. Required: name (string). Optional: type (string, one of "leads" | "companies" | "custom"; default "custom"), sharing (string controlling visibility — see below; default "Private"), fields (object of column definitions, only when not using a template), templateId (string, when creating from a template).

sharing values:

  • "Private" (default): only the creating user can view or modify the list.
  • "Shared": any user in the same company can view and modify the list.
  • "Public": anyone with the list ID can read the list and its rows via the public endpoints (GET /public/lists/ and GET /public/lists//rows). Only the list owner can change sharing afterward.
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

Newly-created list (id and name)

Response returned after creating a list. Includes the list's column headers so callers know the exact column names/types to read or write rows against — no follow-up request is needed.

id
string

ID (UUID) of the newly created list

name
string

Name of the newly created list

type
string

List type: "leads", "companies", or "custom"

headers
object[]

Ordered column definitions created for the list. Use these column names when adding or updating rows.