Skip to main content

Create one lead. Safe to call once per row, forever.

POST 
/api/v1/leads

Creates a single lead and fires the lead.created webhook so an automation can text them within a minute. Built for a no-code trigger (a Google Sheets "New Spreadsheet Row" Zap, a website form, a Meta lead relay) that runs once per row.

The list is reused, never created per call. Resolution order: (1) list_id, after checking it belongs to your account (a foreign or unknown id is a 404, never a silent new list); (2) list_name, which finds or creates ONE list with that name and reuses it on every later call, matched case-insensitively; (3) neither, which finds or creates your single default list, "Inbound Leads (API)". Two rows arriving at the same instant resolve to the same list. Contrast POST /v1/leads/bulk, which creates a NEW list on every call by design and would leave you with one list per spreadsheet row.

A repeat phone in the same list is not an error. It returns 200 with the lead that is already there and already_existed: true, and it does NOT fire lead.created, so re-saving a spreadsheet row never re-texts the customer. Dedupe is list-scoped: the same phone in a different list is a new lead. Send an Idempotency-Key header to also make network retries safe.

consent_acknowledged: true is required, the same contract POST /v1/leads/bulk and POST /v1/contacts use. Scope: write_crm.

Request​

Responses​

This phone was already in the list. Nothing was created and lead.created did NOT fire.