Skip to main content
POST
/
api
/
v2
/
leads
/
add
Add leads in bulk to a campaign or list
curl --request POST \
  --url https://api.instantly.ai/api/v2/leads/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leads": [
    {
      "email": "example@example.com",
      "personalization": "Hello, how are you?",
      "website": "https://example.com",
      "last_name": "Doe",
      "first_name": "John",
      "company_name": "Example Inc.",
      "phone": "+1234567890",
      "lt_interest_status": 1,
      "pl_value_lead": "High",
      "assigned_to": "019cc043-9d00-75e0-9e83-192cca9a643e",
      "custom_variables": {
        "past_customer": true,
        "has_tried_competitors": false
      }
    }
  ]
}
'
{
  "status": "success",
  "total_sent": 10,
  "leads_uploaded": 7,
  "in_blocklist": 1,
  "blocklist_used": "019cc043-e39c-7d91-a325-66191be14c42",
  "duplicated_leads": 0,
  "skipped_count": 1,
  "invalid_email_count": 1,
  "incomplete_count": 1,
  "duplicate_email_count": 0,
  "remaining_in_plan": 9993,
  "created_leads": [
    {
      "id": "019cc043-e39c-7d91-a325-661c7a29083c",
      "email": "test@example.com",
      "index": 0
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
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.

Required array length: 1 - 1000 elements
​
campaign_id
string<uuid>

The unique identifier for the campaign to add leads to. Use this field OR list_id, but not both.

Example:

"019cc043-e39c-7d91-a325-6615db0e1b14"

​
list_id
string<uuid>

The unique identifier for the list to add leads to. Use this field OR campaign_id, but not both.

Example:

"019cc043-e39c-7d91-a325-661689b388af"

​
blocklist_id
string<uuid> | null

Optional blocklist ID to check leads against. If omitted, the workspace default blocklist is used.

Example:

"019cc043-e39c-7d91-a325-66171b5e6f00"

​
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.

Example:

"019cc043-e39c-7d91-a325-661890f3723b"

​
verify_leads_on_import
boolean

If true, a background job will be created to verify the email addresses of the imported leads.

Example:

false

​
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.

Example:

true

​
skip_if_in_campaign
boolean

If true, any lead that already exists in ANY campaign in your workspace will be skipped.

Example:

false

​
skip_if_in_list
boolean

If true, any lead that already exists in ANY list in your workspace will be skipped.

Example:

false

Response

A summary of the bulk import operation.

A summary of the bulk import operation.

​
status
string
required

Indicates the request was processed.

Example:

"success"

​
total_sent
integer
required

The total number of leads included in the request payload.

Example:

10

​
leads_uploaded
integer
required

The number of leads that were successfully created.

Example:

7

​
in_blocklist
integer
required

The number of leads that were skipped because their email was found on the blocklist.

Example:

1

​
blocklist_used
null | string
required

The ID of the blocklist that was used for the check.

Example:

"019cc043-e39c-7d91-a325-66191be14c42"

​
duplicated_leads
integer
required

The number of leads that were already in this specific campaign or list and were not re-added.

Example:

0

​
skipped_count
integer
required

The number of leads skipped due to the skip_if_in_... flags being enabled.

Example:

1

​
invalid_email_count
integer
required

The number of leads skipped due to an invalid email format or a missing email address.

Example:

1

​
incomplete_count
integer
required

The number of leads skipped due to missing email and names. Only calculated for lists.

Example:

1

​
duplicate_email_count
integer
required

The number of leads skipped because their email was duplicated within the request payload itself.

Example:

0

​
remaining_in_plan
null | integer
required

The remaining lead uploads in the current billing plan. This value is only present in the response when a campaign_id is provided.

Example:

9993

​
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.

Example:
[
  {
    "id": "019cc043-e39c-7d91-a325-661c7a29083c",
    "email": "test@example.com",
    "index": 0
  }
]