Skip to main content
Leads are the people and companies your workspace might sell to. Think of a Lead as the reusable record for one person or one company. A Lead can appear in many Lists, pick up more attributes over time, move into campaigns, and stay the same Lead instead of being copied into a new row every time.

​
The Simple Model

ThingWhat it meansMain API
LeadOne person or company record/api/leads
Lead Search TaskA background job that finds potential Leads from a natural-language prompt/api/leads/search
Lead Search ResultA raw provider result saved while the result List is populated/api/leads/search/results
ListA named working set of Leads/api/lists and /api/lists/{id}/leads
Lead AttributeExtra data on a Lead, from enrichment or manual edits/api/leads

​
How Leads Flow

  1. Search, import, signals, or another integration finds possible Leads.
  2. Puffle stores the provider results so you can inspect them.
  3. The search task creates or reuses Lead records and attaches them to the result List.
  4. Lists group those Leads for qualification, enrichment, export, or campaign targeting.
  5. Enrichment and manual edits write attributes onto the Lead, so the improved data follows that Lead across Lists.

​
Common API Recipes

​
Find new people

  1. POST /api/leads/search with prompt and fetch_count.
  2. Poll GET /api/leads/search?taskId=... until the task is complete.
  3. Use the list.id from the search response as the populated result List. Pass listId on the initial POST when you want to populate an existing List.
  4. Optionally read raw result rows with GET /api/leads/search/results?taskId=....

​
Create a Lead directly

Use POST /api/leads when you already have structured person or company data. Send stable identifiers when possible, such as LinkedIn URL, work email, company domain, or provider ids, so Puffle can avoid duplicates.

​
Work inside one List

Use GET /api/lists/{id}/leads for List-scoped Lead paging. Use GET /api/lists first when you need to discover the List id.

​
Move toward outreach

Once a List is clean, campaigns can import the List’s person Leads into outreach. The campaign gets its own lead records for outreach state, while the underlying Lead remains available for research, enrichment, and future Lists.

Lists

Organize leads into working sets.

Signals

Prioritize outreach when there is a timely reason to contact someone.