INinstantly
Lead

Move leads to a campaign or list

Changed on

Move leads to a different campaign or list. This endpoint will return a background job that will process the move. The job will be processed in the background and the leads will be moved to the destination campaign or list. You can use the /background-jobs/:id endpoint to check the job status. Note: When using the ids parameter, you must also provide either campaign or list_id to specify which campaign or list to filter the leads from.

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

post/api/v2/leads/move

Request

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

Request body

searchstring

A search string to search the leads against - can be First Name, Last Name, or Email

filterstring

Filter criteria for leads. For custom lead labels, use the interest_status field.

campaignstring uuid

Campaign ID to filter leads

list_idstring uuid

List ID to filter leads

in_campaignboolean

Whether the lead is in a campaign

in_listboolean

Whether the lead is in a list

idsstring[]

Array of lead IDs to include. When using this parameter, you must provide either campaign or list_id to specify which campaign or list to filter the leads from. This parameter acts as a filter within the specified campaign or list, not as a standalone way to select leads. When ids is non-empty, queries, filter, search, excluded_ids, field_filters, assigned_to and esp_code are ignored.

excluded_idsstring[]

Array of lead IDs to exclude

contactsstring[]

Array of emails the leads needs to have

to_campaign_idstring uuid

The ID of the campaign to move the leads to.

to_list_idstring uuid

The ID of the list to move the leads to.

ignore_resource_filter_clausesboolean

Whether to ignore saved lead-finder clauses for the source campaign/list when selecting leads to move.

check_duplicates_in_campaignsboolean

Whether to check duplicates in campaigns.

skip_leads_in_verificationboolean

Whether to skip leads in verification.

skip_invalid_emailsboolean

Whether to leave behind leads whose email verified as invalid or risky. Leads that were never verified still move.

limitnumber

The limit of the number of leads to move.

assigned_tostring uuid

The ID of the user to assign the leads to.

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

The ESP code to move the leads for.

esg_code'0' | '1' | '2' | '3' | '4' | 'all' | 'none'

The ESG code to move the leads for.

copy_leadsboolean

Whether to copy the leads.

check_duplicatesboolean

Whether to check duplicates.

reset_interest_statusboolean

Whether to reset the interest status of leads when moving or copying them. When true, the interest status will be reset. When false, the existing interest status will be preserved; for non-copy campaign-to-campaign moves, opportunities will also be migrated to the target campaign.

Example request

{
  "search": "John Doe",
  "filter": "FILTER_VAL_CONTACTED",
  "campaign": "01a19e6f-792e-7a08-a176-5b90fc62a669",
  "list_id": "01a19e6f-792e-7a08-a176-5b919a81ec1e",
  "in_campaign": true,
  "in_list": true,
  "ids": [
    "01a19e6f-8934-7526-ae42-aa060fd6bd86"
  ],
  "queries": [
    {
      "actionType": "email-open",
      "values": {
        "occurrence-days": 1
      }
    }
  ],
  "excluded_ids": [
    "01a19e6f-792e-7a08-a176-5b93692b5fe5"
  ],
  "contacts": [
    "test@test.com"
  ],
  "to_campaign_id": "01a19e6f-8934-7526-ae42-aa07cdc5b442",
  "to_list_id": "01a19e6f-8934-7526-ae42-aa0826e40458",
  "ignore_resource_filter_clauses": true,
  "check_duplicates_in_campaigns": true,
  "skip_leads_in_verification": true,
  "skip_invalid_emails": true,
  "limit": 10,
  "assigned_to": "01a19e6f-8934-7526-ae42-aa091090bbfb",
  "esp_code": 1,
  "esg_code": "1",
  "copy_leads": true,
  "check_duplicates": true,
  "reset_interest_status": true
}

Response

The requested Background Job

idstring required

Unique identifier for the background job

workspace_idstring uuid required

Workspace ID

user_idstring uuid nullable

The id of the user that triggered the action that created the job

type'move-leads' | 'import-leads' | 'export-leads' | 'update-warmup-accounts' | 'rename-variable' | 'broadcast-ai-generate' | 'broadcast-website-scrape' | 'import-subscribers-from-crm' | 'resync-subscriber-crm-tags' | 'journey-ai-build' | 'delete-leads' required

Type of background job

entity_idstring uuid nullable

The id of the entity that the job is related to

entity_type'list' | 'campaign' | 'workspace' | 'broadcast' | 'subscriber-group-sync' | 'subscriber-group' | 'journey'

Type of entity

progressnumber required

Progress of the job as a percentage (from 0 to 100)

status'pending' | 'in-progress' | 'success' | 'failed' | 'draining' | 'paused' | 'cancelled' required

Job status

created_atstring required

Timestamp when the job was created

updated_atstring required

Timestamp when the job was last updated

Example response

{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "01a19e6f-3f5d-7091-a533-39d9d99d54e7",
  "user_id": "01a19e6f-3f5d-7091-a533-39daa273da2b",
  "type": "move-leads",
  "entity_id": "01a19e6f-3f5d-7091-a533-39db73eee539",
  "entity_type": "list",
  "data": {
    "moved_lead_emails": [
      "jane@example.com",
      "john@example.com"
    ],
    "skipped_duplicate_emails": [
      "jane@example.com"
    ],
    "skipped_in_other_campaigns_emails": [
      "jane@example.com"
    ],
    "skipped_blocklisted_emails": [
      "jane@example.com"
    ]
  },
  "status": "pending",
  "created_at": "2026-11-02T22:44:13.277Z",
  "updated_at": "2026-11-02T22:44:13.277Z"
}

Changes

  • c781051105a8Revision changes
    • warning

      added the new delete-leads enum value to the response property for the response status

    • warning

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

    • warning

      added the new journey-ai-build enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status