---
title: "Add Leads"
method: POST
path: "/api/v1/campaigns/{campaign_id}/leads"
tags: ["Campaigns"]
---

# Add Leads

`POST /api/v1/campaigns/{campaign_id}/leads`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/campaigns/{campaign_id}/leads`
- Auth: HTTP bearer

Adds leads to a campaign. Each lead needs an `email`; any other keys must match the campaign's `lead_schema` (see Get Campaign) and are otherwise ignored and reported in `dropped_fields` — register custom fields first with Update Lead Schema. Re-adding an existing address updates it instead of duplicating, so retries are safe. Accepts up to 1000 leads per call.

Rows without a usable `email` are **skipped, not fatal** — they are counted in `skipped` and the rest of the batch is still added. The call only fails if no row has one.

**Enrolment.** Leads enrol as soon as the campaign has a **published sequence**, whether or not it is active — a lead added to a paused campaign becomes `in_sequence` with its next step held, and starts moving on Resume Campaign. Leads only stay at `added` when no sequence is published yet; Publish Sequence then picks them up.

## Path parameters

- `campaign_id` string, required

## Request body

- object
  - `leads` object[], required: Leads to add. Keys other than `email` must match the campaign's lead schema.
    - `email` string: Lead email address — the identity key

## Response `201`

Default Response

- object
  - `status` integer
  - `message` string
  - `data` object
    - `added` integer: Leads newly created
    - `updated` integer: Existing leads updated
    - `skipped` integer: Rows skipped for a missing or non-string email — the rest of the batch still went in
    - `dropped_fields` string[]: Field names not in the campaign's lead schema, which were ignored

## Other responses

- `400`: No valid leads in the request
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Campaign not found
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)