> ## Documentation Index > Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Leads in Campaign > List, add, update, and remove leads on a draft campaign. The roster endpoint used for all pre-launch lead management. **CLI:** ```bash theme={null} puffle campaign lead --id puffle campaign lead --id --page --limit --status ``` ## Overview A single URL that owns the lead roster for a campaign: * `GET` — paginated list with optional `status` filter. Safe to poll. * `POST` — bulk add leads (1–1000 per call). Deduplicates by email (email campaigns) or LinkedIn URL (LinkedIn campaigns). * `PATCH` — edit one lead's profile fields. * `DELETE` — remove leads by ID list (up to 500) or wipe the roster with `{ all: true }`. Every write method requires the campaign to be in `draft` status. Once the campaign transitions to `launching`/`active`/`paused`/`completed`, the roster is frozen — the API will return `400` on any mutation. ## AI agent notes **Channel identity.** Every lead needs the identity field matching the campaign type: `email` for email campaigns, `linkedin_url` for LinkedIn campaigns. Rows missing the required identity are rejected with a `400` naming the offending index. The other identity field is captured opportunistically when provided and valid (so a LinkedIn campaign can still record `email` when present). **Deduplication semantics.** Add is deduped both within the batch and against existing campaign leads. Identity is normalized before comparison — emails are lowercased; LinkedIn URLs drop trailing slashes and query strings. Duplicates silently fall out of the import count; the response separates `imported` from `duplicates`. **Custom fields.** `custom_fields` is a free-form JSONB record rendered as `%custom_fields.%` in message templates. Use this for per-lead data the built-in columns don't cover (industry, deal size, notes). **Stats sync.** Add and delete both recompute `campaigns.stats` atomically after the write via the `recalculate_campaign_stats` RPC — no manual stat refresh needed. **Polling the list.** `status` filters map to pipeline stages. `pending` is the launch queue; `sent`/`connection_sent`/`connected`/`message_sent` are in-flight; `replied`/`bounced`/`completed`/`timed_out`/`cancelled` are terminal. Use `total` from the response to drive pagination — with under 200 results per page and up to 200 allowed as `limit`, a single fetch often suffices. **Scaling.** Pre-query caps at 100k existing leads for dedup. Above that the DB unique constraint takes over — behavior is unchanged, just slower on write. ## OpenAPI ````yaml get /api/campaigns/{id}/leads openapi: 3.0.3 info: title: Puffle API version: 1.0.0 description: >- HTTP API for the Puffle GTM platform - Feed and Lead Finder search preparation, campaign-backed Outbound execution, Puffle Agent runs, sender management, and Unibox reply workflows. Designed for operation by both humans and autonomous AI agents. Agents should start at the [Agent Playbook](/guides/agent-playbook) which prescribes a workspace-context check (`GET /api/context`) and core user journeys with exact call ordering. contact: name: Puffle Support url: https://puffle.ai servers: - url: https://app.puffle.ai description: Production security: - bearerAuth: [] tags: - name: Campaigns description: >- Campaign-backed Outbound execution. These endpoints manage draft, launching, active, paused, and completed Outbound runs with sequence nodes, contacts, and sender accounts. - name: Accounts description: Signed-in user account, settings, and workspace context endpoints. - name: Billing description: Billing customer portal and account billing endpoints. - name: Senders description: >- Connected sender accounts, email inboxes, sending domains, DNS verification, warmup, and sender capacity. - name: Socials description: >- Read connected LinkedIn and X accounts, review current and archived posts, and reconcile publication status. Creating, editing, scheduling, publishing, OAuth connection, analytics, and mentions remain dashboard-managed workflows and are not part of the public Bearer-token API. paths: /api/campaigns/{id}/leads: get: tags: - Campaigns summary: Get Leads in Campaign description: >- Paginated list of leads attached to the campaign. Supports optional status filtering and returns the total count for pagination math. operationId: getLeadsInCampaign parameters: - name: id in: path required: true schema: type: string description: Campaign UUID - name: page in: query required: false schema: type: integer minimum: 1 maximum: 9007199254740991 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 - name: status in: query required: false schema: type: string responses: '200': description: Page of leads with total count. content: application/json: schema: type: object properties: prospects: type: array items: type: object properties: id: type: string format: uuid campaign_id: type: string format: uuid user_id: type: string format: uuid status: type: string email: type: string format: email nullable: true linkedin_url: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true name: type: string nullable: true company: type: string nullable: true position: type: string nullable: true headline: type: string nullable: true custom_fields: type: object additionalProperties: {} nullable: true source: type: string nullable: true source_ref: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time bounced_at: type: string format: date-time nullable: true replied_at: type: string format: date-time nullable: true current_node_id: type: string format: uuid nullable: true required: - id - campaign_id - user_id - status additionalProperties: {} description: Canonical campaign lead row. total: type: integer minimum: 0 maximum: 9007199254740991 page: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 limit: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - prospects - total - page - limit additionalProperties: false '401': description: Missing or invalid authentication. content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '404': description: Campaign doesn't exist or isn't owned by the caller. content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '500': description: Unexpected server error. content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_... ````