INinstantly
Lead

Create lead

Changed on

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

post/api/v2/leads

Request

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

Request body

campaignstring uuid nullable

Campaign ID associated with the lead

emailstring nullable

Email address of the lead

personalizationstring nullable

Personalization of the lead

websitestring nullable

Website of the lead

last_namestring nullable

Last name of the lead

first_namestring nullable

First name of the lead

company_namestring nullable

Company name of the lead

job_titlestring nullable

Job title of the lead

phonestring nullable

Phone number of the lead

lt_interest_status1 | 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_leadstring nullable

Potential value of the lead

list_idstring uuid nullable

List ID associated with the lead

assigned_tostring uuid nullable

ID of the user assigned to the lead

skip_if_in_workspaceboolean

Whether to skip if the lead is already in the workspace.

skip_if_in_campaignboolean

Whether to skip if the lead is already in the campaign.

skip_if_in_listboolean

Whether to skip if the lead is already in the list.

blocklist_idstring uuid

The ID of the blocklist to check for the lead.

verify_leads_for_lead_finderboolean

Whether to verify the leads for the lead finder.

verify_leads_on_importboolean

Whether to verify the leads on import.

custom_variablesobject

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

Example request

{
  "campaign": "01a19e6e-1ae3-7a98-870b-d9a9495636e1",
  "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",
  "list_id": "01a19e6e-1ae3-7a98-870b-d9ae0245aaef",
  "assigned_to": "01a19e6e-1ae3-7a98-870b-d9b0e1976e33",
  "skip_if_in_workspace": true,
  "skip_if_in_campaign": true,
  "skip_if_in_list": true,
  "blocklist_id": "01a19e6e-66d0-759c-b698-577d31468f3e",
  "verify_leads_for_lead_finder": true,
  "verify_leads_on_import": true,
  "custom_variables": {
    "past_customer": true,
    "has_tried_competitors": false
  }
}

Response

The Lead

idstring uuid required

Unique identifier for the lead

timestamp_createdstring date-time required

Timestamp when the lead was created

timestamp_updatedstring date-time required

Timestamp when the lead was last updated

organizationstring uuid required

Organization ID associated with the lead

campaignstring uuid nullable

Campaign ID associated with the lead

status1 | 2 | 3 | -1 | -2 | -3 required

Status of the lead

emailstring nullable

Email address of the lead

personalizationstring nullable

Personalization of the lead

websitestring nullable

Website of the lead

last_namestring nullable

Last name of the lead

first_namestring nullable

First name of the lead

company_namestring nullable

Company name of the lead

job_titlestring nullable

Job title of the lead

phonestring nullable

Phone number of the lead

email_open_countnumber required

Number of times the email was opened

email_reply_countnumber required

Number of times the email was replied to

email_click_countnumber required

Number of times the email was clicked

company_domainstring required

Company domain of the lead

last_step_fromstring nullable

Source of the last step

last_step_idstring uuid nullable

ID of the last step

last_step_timestamp_executedstring date-time nullable

Timestamp when the last step was executed

email_opened_stepnumber nullable

Last email step opened by the lead

email_opened_variantnumber nullable

Last step variant opened by the lead

email_replied_stepnumber nullable

Last email step the lead has replied to

email_replied_variantnumber nullable

Last step variant the lead has replied to

email_clicked_stepnumber nullable

Last email step the lead has clicked

email_clicked_variantnumber nullable

Last step variant the lead has clicked

lt_interest_status1 | 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

subsequence_idstring nullable

ID of the subsequence

verification_status0 | 1 | -1 | -2 | -3 | -4 | 11 | 12

Verification status of the lead

pl_value_leadstring nullable

Potential value of the lead

timestamp_added_subsequencestring date-time nullable

Timestamp when the lead was added to the subsequence

timestamp_last_contactstring date-time nullable

Timestamp of the last contact with the lead

timestamp_last_openstring date-time nullable

Timestamp of the last email open

timestamp_last_replystring date-time nullable

Timestamp of the last email reply

timestamp_last_interest_changestring date-time nullable

Timestamp of the last interest status change

timestamp_last_clickstring date-time nullable

Timestamp of the last email click

enrichment_status1 | -1 | 11 | -2

Enrichment status of the lead

list_idstring uuid nullable

List ID associated with the lead

last_contacted_fromstring nullable

Source of the last contact

uploaded_by_userstring uuid nullable

ID of the user who uploaded the lead

upload_method'manual' | 'api' | 'website-visitor'

Method used to upload the lead

assigned_tostring uuid nullable

ID of the user assigned to the lead

is_website_visitorboolean nullable

Indicates if the lead is a website visitor

timestamp_last_touchstring date-time nullable

Timestamp of the last touch with the lead

esp_code0 | 1 | 2 | 3 | 8 | 9 | 10 | 12 | 13 | 999 | 1000

ESP code associated with the lead

esg_code0 | 1 | 2 | 3 | 4

ESG code associated with the lead

Example response

{
  "id": "01a19e6e-1ae1-7ccc-ba2d-8620a50c5d43",
  "timestamp_created": "2026-11-02T22:42:58.403Z",
  "timestamp_updated": "2026-11-02T22:42:58.403Z",
  "organization": "01a19e6e-1ae3-7a98-870b-d9a832dcc425",
  "campaign": "01a19e6e-1ae3-7a98-870b-d9a9495636e1",
  "status": 1,
  "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",
  "company_domain": "example.com",
  "status_summary": {
    "lastStep": {
      "from": "campaign",
      "stepID": "01a19e6e-1ae3-7a98-870b-d9aa5445bc30",
      "timestamp_executed": "2026-11-02T22:42:58.403Z"
    },
    "domain_complete": true
  },
  "payload": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "jobTitle": "Head of Growth",
    "website": "https://example.com",
    "phone": "+1234567890",
    "personalization": "Hi {{first_name}}, I noticed you work at {{company_name}}..."
  },
  "status_summary_subseq": {
    "from": "campaign",
    "stepID": "01a19e6e-1ae3-7a98-870b-d9ab287dfc83",
    "timestampExecuted": "2026-11-02T22:42:58.403Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01a19e6e-1ae3-7a98-870b-d9ac98994042",
  "last_step_timestamp_executed": "2026-11-02T22:42:58.403Z",
  "email_opened_step": 1,
  "email_opened_variant": 1,
  "email_replied_step": 1,
  "email_replied_variant": 1,
  "email_clicked_step": 1,
  "email_clicked_variant": 1,
  "lt_interest_status": 1,
  "subsequence_id": "01a19e6e-1ae3-7a98-870b-d9adab1a2faa",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2026-11-02T22:42:58.403Z",
  "timestamp_last_contact": "2026-11-02T22:42:58.403Z",
  "timestamp_last_open": "2026-11-02T22:42:58.403Z",
  "timestamp_last_reply": "2026-11-02T22:42:58.403Z",
  "timestamp_last_interest_change": "2026-11-02T22:42:58.403Z",
  "timestamp_last_click": "2026-11-02T22:42:58.403Z",
  "enrichment_status": 1,
  "list_id": "01a19e6e-1ae3-7a98-870b-d9ae0245aaef",
  "last_contacted_from": "email",
  "uploaded_by_user": "01a19e6e-1ae3-7a98-870b-d9af4b867712",
  "upload_method": "manual",
  "assigned_to": "01a19e6e-1ae3-7a98-870b-d9b0e1976e33",
  "is_website_visitor": true,
  "timestamp_last_touch": "2026-11-02T22:42:58.403Z",
  "esp_code": 1,
  "esg_code": 1
}

Changes

  • c781051105a8Revision changes
    • warning

      added the new 0.00 enum value to the response property for the response status