Move leads to a campaign or list

curl --request POST \
  --url https://api.instantly.ai/api/v2/leads/move \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "019cc043-af1d-74f8-bb1a-ebd9220e8d8e",
  "type": "move-leads",
  "progress": 0,
  "status": "pending",
  "created_at": "2026-03-05T23:09:47.165Z",
  "updated_at": "2026-03-05T23:09:47.165Z",
  "user_id": "019cc043-af1d-74f8-bb1a-ebdaab2b64ce",
  "entity_id": "019cc043-af1d-74f8-bb1a-ebdb698900fd",
  "entity_type": "list",
  "data": {}
}

Lead

Move leads to a campaign or list

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

leads

move

Move leads to a campaign or list

curl --request POST \
  --url https://api.instantly.ai/api/v2/leads/move \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "019cc043-af1d-74f8-bb1a-ebd9220e8d8e",
  "type": "move-leads",
  "progress": 0,
  "status": "pending",
  "created_at": "2026-03-05T23:09:47.165Z",
  "updated_at": "2026-03-05T23:09:47.165Z",
  "user_id": "019cc043-af1d-74f8-bb1a-ebdaab2b64ce",
  "entity_id": "019cc043-af1d-74f8-bb1a-ebdb698900fd",
  "entity_type": "list",
  "data": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

string

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

Example:

"John Doe"

filter

string

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

Example:

"FILTER_VAL_CONTACTED"

campaign

string<uuid>

Campaign ID to filter leads

Example:

"019cc043-d74d-7eae-885a-00dbd6697052"

list_id

string<uuid>

List ID to filter leads

Example:

"019cc043-d74d-7eae-885a-00dcbf3b1304"

in_campaign

boolean

Whether the lead is in a campaign

Example:

true

in_list

boolean

Whether the lead is in a list

Example:

true

ids

string<uuid>[]

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.

queries

object[]

Show child attributes

excluded_ids

string<uuid>[]

Array of lead IDs to exclude

contacts

string<email>[]

Array of emails the leads needs to have

to_campaign_id

string<uuid>

The ID of the campaign to move the leads to.

Example:

"019cc043-e39b-7dd6-85d5-1293a6cbba14"

to_list_id

string<uuid>

The ID of the list to move the leads to.

Example:

"019cc043-e39b-7dd6-85d5-129417356f81"

ignore_resource_filter_clauses

boolean

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

Example:

true

check_duplicates_in_campaigns

boolean

Whether to check duplicates in campaigns.

Example:

true

skip_leads_in_verification

boolean

Whether to skip leads in verification.

Example:

true

limit

number

The limit of the number of leads to move.

Example:

10

assigned_to

string<uuid>

The ID of the user to assign the leads to.

Example:

"019cc043-e39b-7dd6-85d5-12957209d4c8"

esp_code

enum<number>

The ESP code to move the leads for.

Available options:

0,

1,

2,

3,

8,

9,

10,

12,

13,

999,

1000

Example:

1

esg_code

enum<string>

The ESG code to move the leads for.

Available options:

0,

1,

2,

3,

4,

all,

none

Example:

"1"

copy_leads

boolean

Whether to copy the leads.

Example:

true

check_duplicates

boolean

Whether to check duplicates.

Example:

true

reset_interest_status

boolean

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.

Example:

true

Response

The requested Background Job

A background job that can be used to perform long-running tasks

string

required

Unique identifier for the background job

Example:

"675266e304a8e55b17f0228b"

workspace_id

string<uuid>

required

Workspace ID

Example:

"019cc043-af1d-74f8-bb1a-ebd9220e8d8e"

type

enum<string>

required

Type of background job

Available options:

move-leads,

import-leads,

export-leads,

update-warmup-accounts,

rename-variable

Example:

"move-leads"

progress

number

required

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

Required range: 0 <= x <= 100

Example:

0

status

enum<string>

required

Job status

Available options:

pending,

in-progress,

success,

failed

Example:

"pending"

created_at

string

required

Timestamp when the job was created

Example:

"2026-03-05T23:09:47.165Z"

updated_at

string

required

Timestamp when the job was last updated

Example:

"2026-03-05T23:09:47.165Z"

user_id

null | string<uuid>

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

Example:

"019cc043-af1d-74f8-bb1a-ebdaab2b64ce"

entity_id

null | string<uuid>

The id of the entity that the job is related to

Example:

"019cc043-af1d-74f8-bb1a-ebdb698900fd"

entity_type

enum<string>

Type of entity

Available options:

list,

campaign,

workspace

Example:

"list"

data

object

Data about the job, used to store any additional information we need to process the job

Merge two leads Bulk assign leads to organization users

⌘I

Overview

Getting Started

Guides

Resources

Schemas

Move leads to a campaign or list

Authorizations

Body

Response