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.

headers
object[]

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

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"