---
title: "Add leads in bulk to a campaign or list"
method: POST
path: "/api/v2/leads/add"
tags: ["Lead"]
---

# Add leads in bulk to a campaign or list

`POST /api/v2/leads/add`

Adds up to 1000 leads to either a campaign or a list. You must provide a `campaign_id` or a `list_id`, but not both. The endpoint validates emails, checks against blocklists and existing leads.


Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`

## Request body

- object
  - `campaign_id` string, uuid — The unique identifier for the campaign to add leads to. Use this field OR `list_id`, but not both.
  - `list_id` string, uuid — The unique identifier for the list to add leads to. Use this field OR `campaign_id`, but not both.
  - `leads` object[], required — An array of lead objects to create. When using `campaign_id`: Each lead object must contain an `email`. When using `list_id` Each lead object must contain at least one of the following: `email`, `first_name`, or `last_name`.
    - `email` string, nullable — Email address of the lead
    - `personalization` string, nullable — Personalization of the lead
    - `website` string, nullable — Website of the lead
    - `last_name` string, nullable — Last name of the lead
    - `first_name` string, nullable — First name of the lead
    - `company_name` string, nullable — Company name of the lead
    - `job_title` string, nullable — Job title of the lead
    - `phone` string, nullable — Phone number of the lead
    - `lt_interest_status` 1 | 2 | 3 | 4 | 0 | -1 | -2 | -3 | -4 — Lead interest status. It can be either a static value (check below), or a custom status interest value
    - `pl_value_lead` string, nullable — Potential value of the lead
    - `assigned_to` string, uuid, nullable — ID of the user assigned to the lead
    - `custom_variables` object — Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field
  - `blocklist_id` string, uuid, nullable — Optional blocklist ID to check leads against. If omitted, the workspace default blocklist is used.
  - `assigned_to` string, uuid — Optional user ID to assign all imported leads to. If omitted, leads are assigned to the campaign owner when `campaign_id` is defined, or the user making the request.
  - `verify_leads_on_import` boolean — If true, a background job will be created to verify the email addresses of the imported leads.
  - `skip_if_in_workspace` boolean — If true, any lead that already exists anywhere in your workspace (in any campaign or list) will be skipped. This option overrides the other "skip_if" flags.
  - `skip_if_in_campaign` boolean — If true, any lead that already exists in ANY campaign in your workspace will be skipped.
  - `skip_if_in_list` boolean — If true, any lead that already exists in ANY list in your workspace will be skipped.

## Response `200`

A summary of the bulk import operation.

- object — A summary of the bulk import operation.
  - `status` string, required — Indicates the request was processed.
  - `total_sent` integer, required — The total number of leads included in the request payload.
  - `leads_uploaded` integer, required — The number of leads that were successfully created.
  - `in_blocklist` integer, required — The number of leads that were skipped because their email was found on the blocklist.
  - `blocklist_used` string, nullable, required — The ID of the blocklist that was used for the check.
  - `duplicated_leads` integer, required — The number of leads that were already in this specific campaign or list and were not re-added.
  - `skipped_count` integer, required — The number of leads skipped due to the `skip_if_in_...` flags being enabled.
  - `invalid_email_count` integer, required — The number of leads skipped due to an invalid email format or a missing email address.
  - `incomplete_count` integer, required — The number of leads skipped due to missing email and names. Only calculated for lists.
  - `duplicate_email_count` integer, required — The number of leads skipped because their email was duplicated within the request payload itself.
  - `remaining_in_plan` integer, nullable, required — The remaining lead uploads in the current billing plan. This value is only present in the response when a `campaign_id` is provided.
  - `created_leads` object[], required — A list of created leads with their summary information. You can use this to map your input to the created leads.
    - `index` integer, required — The index of the lead in the input array. For leads that have no email address you can use this field as the key to your input leads.
    - `id` string, uuid, required — The ID of the lead. Use it for GET, DELETE or PATCH operations.
    - `email` string, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `phone` string, nullable

## Other responses

- `401` — This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402` — This request cannot be fulfilled because the workspace does not have an active paid plan
- `404` — The requested resource was not found
- `429` — You have exceeded the rate limit. Please check the rate limit docs for more information.

---

[API](https://skmtc.net/instantly/apis/api-explorer.md) · [All operations](https://skmtc.net/instantly/apis/api-explorer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instantly/api-explorer/versions/378d1e253fe7/schema)