Skip to main content
POST
Create Lead List
A list owns leads. listId is what you pass to POST /api/leads to file new leads somewhere specific, and to POST /api/leads/check-availability to check a whole list at once. These endpoints are how you get a listId without opening the dashboard.
Creates an empty list, or creates one and fills it in the same call by passing contacts.

Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

Request body

string
required
List name. Must be unique in the workspace — a duplicate returns 400 List name already exists with code: "NAME_EXISTS". A missing or non-string name returns 400 with code: "NAME_REQUIRED".
string
Optional description.
object[]
Optional. Seed the list with leads in the same call. Same per-lead shape as POST /api/leads — firstName, lastName, phone, email, companyName, customFields, and so on. Prefer phone in E.164 as the identifier.When present, the response is the import shape (listId, savedCount, duplicateCount) rather than the list object.
string
default:"api"
Origin label stored on the created leads, e.g. "api" or "gohighlevel". Only used with contacts.
string
GoHighLevel location id, stored on the created leads. Only applied when source is "gohighlevel".

Example — empty list

Success (200 OK)

Example — create and seed in one call

Success (200 OK)

Take listId from either response shape and pass it to POST /api/leads to add more leads later.

Errors