---
title: "POST /v1/add_leads"
method: POST
path: "/v1/add_leads"
tags: ["GTM verbs"]
---

# POST /v1/add_leads

`POST /v1/add_leads`

## Request

- Base URL: `https://api.layrcake.dev`
- URL: `https://api.layrcake.dev/v1/add_leads`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `campaign_id` string, uuid, required
  - `leads` object[]
    - `email` string, required
    - `first_name` string
    - `last_name` string
    - `company_name` string
    - `location` string
    - `custom` object
  - `finalize_incomplete` boolean
  - `confirmation_token` string
  - `dry_run` boolean

## Response `200`

Successful outcome

- object
  - `result` union, required
    - object
      - `history_available` boolean
      - `campaign_id` string, uuid, required
      - `state` 'draft' | 'incomplete' | 'active' | 'paused', required
      - `leads_accepted` integer, required
      - `leads_correlated` integer, required
      - `leads_pending` integer, required
      - `leads_rejected` integer, required
      - `leads_suppressed` integer, required
      - `campaign_lead_total` integer, required
      - `removed` object
        - `opted_out` integer, required
        - `do_not_contact` integer
        - `no_location` integer
        - `excluded` integer
        - `invalid` integer, required
        - `platform_blocked` integer, required
        - `contacted_recently` integer
        - `capped` integer, required
        - `other` integer, required
        - `total` integer, required
      - `removed_examples` string[]
      - `confirmation_token` string
      - `approval_url` string, uri
      - `approval_email` 'queued' | 'reused' | 'suppressed_rate_limit' | 'no_approver'
    - object
      - `dry_run` true, required
      - `advisory` true, required
      - `evaluated_at` string, required
      - `plan` object, required
        - `verb` 'add_leads', required
        - `plan_version` 3, required
        - `input_version` string, required
        - `credits_estimate` string, required
        - `would_exceed` string[], required
        - `warnings` string[], required
        - `would` object, required
          - `campaign_state` string, nullable, required
          - `leads_new` integer, required
          - `leads_duplicate` integer, required
          - `leads_suppressed` integer, required
          - `removed` object, required
            - `opted_out` integer, required
            - `do_not_contact` integer
            - `no_location` integer
            - `excluded` integer
            - `invalid` integer, required
            - `platform_blocked` integer, required
            - `contacted_recently` integer
            - `capped` integer, required
            - `other` integer, required
            - `total` integer, required
          - `needs_confirmation` boolean, required
          - `history_available` boolean
  - `layrcake` object, required
    - `request_id` string, uuid, required
    - `credits_charged` string, required
    - `credits_available` string, required
    - `replayed` boolean
    - `route` object
      - `used` 'balanced' | 'cheapest' | 'broadest' | 'fastest', required
      - `source` 'request' | 'key' | 'guess' | 'default', required

## Other responses

- `4XX`: Caller, scope, confirmation, or credit error
- `5XX`: Provider or service error

---

[API](https://skmtc.dev/layrcake/apis/layrcake-api.md) · [All operations](https://skmtc.dev/layrcake/apis/layrcake-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layrcake/apis/layrcake-api/revisions/24c80e33c274?raw)