INinstantly
Lead

Add leads in bulk to a campaign or list

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

post/api/v2/leads/add

Request

  • Base URL
    https://api.instantly.ai
  • URL
    https://api.instantly.ai/api/v2/leads/add
  • Auth
    HTTP bearer

Request body

campaign_idstring uuid

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

list_idstring uuid

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

blocklist_idstring uuid nullable

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

assigned_tostring 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_importboolean

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

skip_if_in_workspaceboolean

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_campaignboolean

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

skip_if_in_listboolean

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

Example request

{
  "campaign_id": "01a19e6f-8db8-7ac3-85b5-0c1a2813899b",
  "list_id": "01a19e6f-8db8-7ac3-85b5-0c1b428ff306",
  "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": "01a19e6f-4332-784a-8287-7308f4b71670",
      "custom_variables": {
        "past_customer": true,
        "has_tried_competitors": false
      }
    }
  ],
  "blocklist_id": "01a19e6f-8db8-7ac3-85b5-0c1c753ac29e",
  "assigned_to": "01a19e6f-8db8-7ac3-85b5-0c1da716b119",
  "skip_if_in_workspace": true
}

Response

A summary of the bulk import operation.

statusstring required

Indicates the request was processed.

total_sentinteger required

The total number of leads included in the request payload.

leads_uploadedinteger required

The number of leads that were successfully created.

in_blocklistinteger required

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

blocklist_usedstring nullable required

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

duplicated_leadsinteger required

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

skipped_countinteger required

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

invalid_email_countinteger required

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

incomplete_countinteger required

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

duplicate_email_countinteger required

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

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

Example response

{
  "status": "success",
  "total_sent": 10,
  "leads_uploaded": 7,
  "in_blocklist": 1,
  "blocklist_used": "01a19e6f-8db8-7ac3-85b5-0c1e739aebd9",
  "skipped_count": 1,
  "invalid_email_count": 1,
  "incomplete_count": 1,
  "remaining_in_plan": 9993,
  "created_leads": [
    {
      "id": "01a19e6f-8db8-7ac3-85b5-0c21152198d1",
      "email": "test@example.com",
      "index": 0
    }
  ]
}

Changes

No recorded changes to this operation across all 6 revisions of this API.