Skip to main content
POST
/
api
/
lists
Create a list
curl --request POST \
  --url https://app.puffle.ai/api/lists \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'
{ "sheet": { "id": "a1111111-1111-1111-1111-111111111111", "userId": "u1111111-1111-1111-1111-111111111111", "name": "Series A fintech founders", "enrichmentStatus": "idle", "createdAt": "2026-04-22T10:00:00Z", "updatedAt": "2026-04-22T10:00:00Z", "activeSearchId": null, "searchFilters": null } }

​
Overview

Create a new empty list and seed it with 11 built-in columns. Common next steps: POST /api/lists/{id}/rows to add rows manually, POST /api/lists/{id}/import for a CSV, POST /api/lists/import-sales-nav for a Sales Navigator URL, or POST /api/leads/search with the new list’s id to kick off a lead search that auto-populates rows. If built-in column seeding fails, the list row is rolled back so you never end up with an orphan “half-initialized” list.
This operation shares the URL path /api/lists with other verbs. See the sibling page for related operations on the same resource.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a new empty list. The list is seeded with 11 built-in columns (name, role, company, location, domain, linkedin, headline, seniority, departments, functions, experience) ready for row imports.

​
name
string

Display name. Defaults to "Untitled Sheet" when omitted or blank.

Response

List created. Returns the full list summary; row/company counts start at 0.

​
sheet
object
required

The freshly created list. No row/company counts attached — the list is empty until rows are imported.