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.",
      "job_title": "Head of Growth",
      "phone": "+1234567890",
      "lt_interest_status": 1,
      "pl_value_lead": "High",
      "assigned_to": "019f985c-48b6-7e4c-bfdc-978cfa544bdc",
      "custom_variables": {
        "past_customer": true,
        "has_tried_competitors": false
      }
    }
  ]
}
'

import requests

url = "https://api.instantly.ai/api/v2/leads/add"

payload = { "leads": [
        {
            "email": "example@example.com",
            "personalization": "Hello, how are you?",
            "website": "https://example.com",
            "last_name": "Doe",
            "first_name": "John",
            "company_name": "Example Inc.",
            "job_title": "Head of Growth",
            "phone": "+1234567890",
            "lt_interest_status": 1,
            "pl_value_lead": "High",
            "assigned_to": "019f985c-48b6-7e4c-bfdc-978cfa544bdc",
            "custom_variables": {
                "past_customer": True,
                "has_tried_competitors": False
            }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    leads: [
      {
        email: 'example@example.com',
        personalization: 'Hello, how are you?',
        website: 'https://example.com',
        last_name: 'Doe',
        first_name: 'John',
        company_name: 'Example Inc.',
        job_title: 'Head of Growth',
        phone: '+1234567890',
        lt_interest_status: 1,
        pl_value_lead: 'High',
        assigned_to: '019f985c-48b6-7e4c-bfdc-978cfa544bdc',
        custom_variables: {past_customer: true, has_tried_competitors: false}
      }
    ]
  })
};

fetch('https://api.instantly.ai/api/v2/leads/add', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.instantly.ai/api/v2/leads/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"leads\": [\n    {\n      \"email\": \"example@example.com\",\n      \"personalization\": \"Hello, how are you?\",\n      \"website\": \"https://example.com\",\n      \"last_name\": \"Doe\",\n      \"first_name\": \"John\",\n      \"company_name\": \"Example Inc.\",\n      \"job_title\": \"Head of Growth\",\n      \"phone\": \"+1234567890\",\n      \"lt_interest_status\": 1,\n      \"pl_value_lead\": \"High\",\n      \"assigned_to\": \"019f985c-48b6-7e4c-bfdc-978cfa544bdc\",\n      \"custom_variables\": {\n        \"past_customer\": true,\n        \"has_tried_competitors\": false\n      }\n    }\n  ]\n}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instantly.ai/api/v2/leads/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'leads' => [
        [
                'email' => 'example@example.com',
                'personalization' => 'Hello, how are you?',
                'website' => 'https://example.com',
                'last_name' => 'Doe',
                'first_name' => 'John',
                'company_name' => 'Example Inc.',
                'job_title' => 'Head of Growth',
                'phone' => '+1234567890',
                'lt_interest_status' => 1,
                'pl_value_lead' => 'High',
                'assigned_to' => '019f985c-48b6-7e4c-bfdc-978cfa544bdc',
                'custom_variables' => [
                                'past_customer' => true,
                                'has_tried_competitors' => false
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instantly.ai/api/v2/leads/add"

	payload := strings.NewReader("{\n  \"leads\": [\n    {\n      \"email\": \"example@example.com\",\n      \"personalization\": \"Hello, how are you?\",\n      \"website\": \"https://example.com\",\n      \"last_name\": \"Doe\",\n      \"first_name\": \"John\",\n      \"company_name\": \"Example Inc.\",\n      \"job_title\": \"Head of Growth\",\n      \"phone\": \"+1234567890\",\n      \"lt_interest_status\": 1,\n      \"pl_value_lead\": \"High\",\n      \"assigned_to\": \"019f985c-48b6-7e4c-bfdc-978cfa544bdc\",\n      \"custom_variables\": {\n        \"past_customer\": true,\n        \"has_tried_competitors\": false\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "status": "success",
  "total_sent": 10,
  "leads_uploaded": 7,
  "in_blocklist": 1,
  "blocklist_used": "019f985c-9365-7f63-975b-33aea7e8e8b9",
  "duplicated_leads": 0,
  "skipped_count": 1,
  "invalid_email_count": 1,
  "incomplete_count": 1,
  "duplicate_email_count": 0,
  "remaining_in_plan": 9993,
  "created_leads": [
    {
      "id": "019f985c-9365-7f63-975b-33b1dbca2180",
      "email": "test@example.com",
      "index": 0
    }
  ]
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Workspace does not have an active paid plan"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

POST

api

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.",
      "job_title": "Head of Growth",
      "phone": "+1234567890",
      "lt_interest_status": 1,
      "pl_value_lead": "High",
      "assigned_to": "019f985c-48b6-7e4c-bfdc-978cfa544bdc",
      "custom_variables": {
        "past_customer": true,
        "has_tried_competitors": false
      }
    }
  ]
}
'

import requests

url = "https://api.instantly.ai/api/v2/leads/add"

payload = { "leads": [
        {
            "email": "example@example.com",
            "personalization": "Hello, how are you?",
            "website": "https://example.com",
            "last_name": "Doe",
            "first_name": "John",
            "company_name": "Example Inc.",
            "job_title": "Head of Growth",
            "phone": "+1234567890",
            "lt_interest_status": 1,
            "pl_value_lead": "High",
            "assigned_to": "019f985c-48b6-7e4c-bfdc-978cfa544bdc",
            "custom_variables": {
                "past_customer": True,
                "has_tried_competitors": False
            }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    leads: [
      {
        email: 'example@example.com',
        personalization: 'Hello, how are you?',
        website: 'https://example.com',
        last_name: 'Doe',
        first_name: 'John',
        company_name: 'Example Inc.',
        job_title: 'Head of Growth',
        phone: '+1234567890',
        lt_interest_status: 1,
        pl_value_lead: 'High',
        assigned_to: '019f985c-48b6-7e4c-bfdc-978cfa544bdc',
        custom_variables: {past_customer: true, has_tried_competitors: false}
      }
    ]
  })
};

fetch('https://api.instantly.ai/api/v2/leads/add', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.instantly.ai/api/v2/leads/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"leads\": [\n    {\n      \"email\": \"example@example.com\",\n      \"personalization\": \"Hello, how are you?\",\n      \"website\": \"https://example.com\",\n      \"last_name\": \"Doe\",\n      \"first_name\": \"John\",\n      \"company_name\": \"Example Inc.\",\n      \"job_title\": \"Head of Growth\",\n      \"phone\": \"+1234567890\",\n      \"lt_interest_status\": 1,\n      \"pl_value_lead\": \"High\",\n      \"assigned_to\": \"019f985c-48b6-7e4c-bfdc-978cfa544bdc\",\n      \"custom_variables\": {\n        \"past_customer\": true,\n        \"has_tried_competitors\": false\n      }\n    }\n  ]\n}")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.instantly.ai/api/v2/leads/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'leads' => [
        [
                'email' => 'example@example.com',
                'personalization' => 'Hello, how are you?',
                'website' => 'https://example.com',
                'last_name' => 'Doe',
                'first_name' => 'John',
                'company_name' => 'Example Inc.',
                'job_title' => 'Head of Growth',
                'phone' => '+1234567890',
                'lt_interest_status' => 1,
                'pl_value_lead' => 'High',
                'assigned_to' => '019f985c-48b6-7e4c-bfdc-978cfa544bdc',
                'custom_variables' => [
                                'past_customer' => true,
                                'has_tried_competitors' => false
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.instantly.ai/api/v2/leads/add"

	payload := strings.NewReader("{\n  \"leads\": [\n    {\n      \"email\": \"example@example.com\",\n      \"personalization\": \"Hello, how are you?\",\n      \"website\": \"https://example.com\",\n      \"last_name\": \"Doe\",\n      \"first_name\": \"John\",\n      \"company_name\": \"Example Inc.\",\n      \"job_title\": \"Head of Growth\",\n      \"phone\": \"+1234567890\",\n      \"lt_interest_status\": 1,\n      \"pl_value_lead\": \"High\",\n      \"assigned_to\": \"019f985c-48b6-7e4c-bfdc-978cfa544bdc\",\n      \"custom_variables\": {\n        \"past_customer\": true,\n        \"has_tried_competitors\": false\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "status": "success",
  "total_sent": 10,
  "leads_uploaded": 7,
  "in_blocklist": 1,
  "blocklist_used": "019f985c-9365-7f63-975b-33aea7e8e8b9",
  "duplicated_leads": 0,
  "skipped_count": 1,
  "invalid_email_count": 1,
  "incomplete_count": 1,
  "duplicate_email_count": 0,
  "remaining_in_plan": 9993,
  "created_leads": [
    {
      "id": "019f985c-9365-7f63-975b-33b1dbca2180",
      "email": "test@example.com",
      "index": 0
    }
  ]
}

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Workspace does not have an active paid plan"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

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

Show child attributes

campaign_id

string<uuid>

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

Example:

"019f985c-9365-7f63-975b-33aa13ea6de1"

list_id

string<uuid>

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

Example:

"019f985c-9365-7f63-975b-33abd893d408"

blocklist_id

string<uuid> | null

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

Example:

"019f985c-9365-7f63-975b-33ac1c49695c"

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:

"019f985c-9365-7f63-975b-33ad7e50027b"

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.

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:

"019f985c-9365-7f63-975b-33aea7e8e8b9"

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.

Show child attributes

Example:

[
  {
    "id": "019f985c-9365-7f63-975b-33b1dbca2180",
    "email": "test@example.com",
    "index": 0
  }
]

Move a lead to a subsequence Initialize google oauth

⌘I

Overview

Getting Started

Guides

Resources

Schemas

Add leads in bulk to a campaign or list

Authorizations

Body

Response