INinstantly
Lead

Merge two leads

Changed on

Merge two leads

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

post/api/v2/leads/merge

Request

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

Request body

lead_idstring uuid required

The ID of the lead to merge.

destination_lead_idstring uuid required

The ID of the destination lead to merge into.

Example request

{
  "lead_id": "01a19e6f-8db3-7b5c-93bd-70e429257b87",
  "destination_lead_id": "01a19e6f-8db3-7b5c-93bd-70e5c5dfdfc3"
}

Response

The requested 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": "01a19e6f-4330-79e9-a497-79454aceef1f",
  "timestamp_created": "2026-11-02T22:44:14.258Z",
  "timestamp_updated": "2026-11-02T22:44:14.258Z",
  "organization": "01a19e6f-4332-784a-8287-7300a1421c37",
  "campaign": "01a19e6f-4332-784a-8287-73010d212915",
  "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": "01a19e6f-4332-784a-8287-730267ef2465",
      "timestamp_executed": "2026-11-02T22:44:14.258Z"
    },
    "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": "01a19e6f-4332-784a-8287-7303fe5275f9",
    "timestampExecuted": "2026-11-02T22:44:14.258Z"
  },
  "last_step_from": "campaign",
  "last_step_id": "01a19e6f-4332-784a-8287-7304494ef66f",
  "last_step_timestamp_executed": "2026-11-02T22:44:14.258Z",
  "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": "01a19e6f-4332-784a-8287-730565c14959",
  "verification_status": 1,
  "pl_value_lead": "High",
  "timestamp_added_subsequence": "2026-11-02T22:44:14.258Z",
  "timestamp_last_contact": "2026-11-02T22:44:14.258Z",
  "timestamp_last_open": "2026-11-02T22:44:14.258Z",
  "timestamp_last_reply": "2026-11-02T22:44:14.258Z",
  "timestamp_last_interest_change": "2026-11-02T22:44:14.258Z",
  "timestamp_last_click": "2026-11-02T22:44:14.258Z",
  "enrichment_status": 1,
  "list_id": "01a19e6f-4332-784a-8287-7306019aeb8e",
  "last_contacted_from": "email",
  "uploaded_by_user": "01a19e6f-4332-784a-8287-73079e2c68dd",
  "upload_method": "manual",
  "assigned_to": "01a19e6f-4332-784a-8287-7308f4b71670",
  "is_website_visitor": true,
  "timestamp_last_touch": "2026-11-02T22:44:14.258Z",
  "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