Skip to main content
POST
/
api
/
lists
/
{id}
/
columns
Create a list column
curl --request POST \
  --url https://app.puffle.ai/api/lists/{id}/columns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "isDynamic": true,
  "prompt": "<string>",
  "subject": "person",
  "dataSource": "web",
  "enrichmentType": "work_email",
  "schema": {
    "type": "text",
    "format": "plain",
    "currency": "USD",
    "scale": "none",
    "textFormat": "short",
    "options": [
      "<string>"
    ],
    "itemType": "text",
    "maxItems": 4503599627370495,
    "linkType": "generic"
  },
  "config": {},
  "isPreview": true
}
'
{ "column": { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "listId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "<string>", "prompt": "<string>", "responseType": "auto", "source": "profile", "subject": "person", "isFilter": true, "position": 4503599627370495, "schema": { "type": "text", "format": "plain", "currency": "USD", "scale": "none", "textFormat": "short", "options": [ "<string>" ], "itemType": "text", "maxItems": 4503599627370495, "linkType": "generic" }, "enrichmentType": "work_email", "config": {}, "createdAt": "2023-11-07T05:31:56Z", "isPreview": true, "category": "built-in", "builtInKey": "<string>" } }

​
Overview

Creates a single column on a list and immediately dispatches a Trigger.dev enrichment task for the existing rows. The task family depends on the enrichmentType + subject:
  • work_email / mobile_phone (people only) -> list-contact-enrich (FullEnrich)
  • hiring_status (companies only) -> list-hiring-enrich
  • site_crawl, website_overview, news_articles, linkedin_posts -> list-generic-enrich via the adapter framework
  • Dynamic prompt column with no explicit type -> ai (runs sheet-ai-enrich in batches of 100)
Credits are previewed before the column is created; the request returns 402 if the caller can’t afford enrichment across every row. Credits are only deducted after the task dispatch succeeds, and contact enrichment defers its deduction to the task itself (charges only rows actually sent to FullEnrich). When isPreview: true, only the first 3 rows are enriched so the user can preview results before committing. Promote the preview column later with PATCH /api/lists/{id}/columns/{colId} using isPreview: false.

​
AI agent notes

Preconditions:
  • The list must exist and be owned by the caller.
  • Only one hiring_status column per list — the server returns 400 if another exists.
  • Dynamic columns must provide a non-empty prompt. If no schema is supplied, the server infers one from the prompt.
Postconditions:
  • list_cells / list_company_cells rows are created with status: pending for every existing row (or the first 3 when isPreview).
  • trigger_run_ids is persisted on the column row so DELETE /api/lists/{id}/columns/{colId} can cancel in-flight runs.
Polling for results:
  • Preview columns: GET /api/lists/{id}/columns/{colId}/preview-cells at ~2 s cadence until every cell reports terminal status.
  • Full columns: use Supabase Realtime or poll the cells table directly.
Credits:
  • Pre-flight check is advisory — if it passes, the column is created and credits are deducted after dispatch. If it fails, the column is not created and no credits move.
  • Contact enrichment (work_email/mobile_phone) tracks credits inside the task, per-row, only for rows actually queried against FullEnrich.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

List UUID. Must be owned by the caller.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

Column creation payload. Rows are enriched in the background by the appropriate Trigger.dev task; an asynchronous enrichment run is dispatched on creation.

​
name
string
required

Display name. Required, must be non-empty after trim.

Minimum string length: 1
​
isDynamic
boolean
required

True when the column is AI-populated (has a prompt) vs a static column with no automation.

​
prompt
string

AI instruction text. Required for dynamic AI columns; ignored otherwise.

​
subject
enum<string>

Column subject. Defaults to person; invalid values are coerced to person.

Available options:
person,
company
​
dataSource
enum<string>

For dynamic columns only. web triggers live web search; profile uses internal profile data only. Defaults to web when a prompt is provided.

Available options:
web,
profile
​
enrichmentType
enum<string>

Explicit enrichment type. When omitted, dynamic columns default to ai. hiring_status is capped at one per list (400 if another exists).

Available options:
work_email,
mobile_phone,
site_crawl,
website_overview,
hiring_status,
news_articles,
linkedin_posts
​
schema
object

Structured schema for cell values — drives UI formatting, enum validation, and list-item type coercion.

​
config
object

Enrichment config. Currently supports { timePeriod: "1m"|"3m"|"6m"|"1y"|"all" } for news columns.

​
isPreview
boolean

If true, creates a preview column limited to 3 rows. Promote later with PATCH isPreview: false.

Response

Column created. Enrichment task(s) have been dispatched asynchronously — poll GET /api/lists/{id}/columns/{colId}/preview-cells (or read list_cells) for results.

​
column
object
required

A column on a list. Stored as list_columns; its values live in list_cells (people) or list_company_cells (companies).