> ## Documentation Index > Fetch the complete documentation index at: https://developer.instantly.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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` ## OpenAPI ````yaml https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/move openapi: 3.1.0 info: title: API Explorer description: >- The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text. version: 2.0.0 servers: - url: https://api.instantly.ai description: Instantly API Server security: - ApiKeyAuth: [] tags: - name: Analytics description: Endpoints related to analytics x-displayName: Analytics - name: OAuth description: >- OAuth authentication endpoints for connecting Google and Microsoft email accounts x-displayName: OAuth - name: Account description: An email account that can be used to send campaigns x-displayName: Account - name: Campaign description: A campaign that can be sent to a list of recipients x-displayName: Campaign - name: Email description: >- A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox x-displayName: Email - name: EmailVerification description: A single email verification x-displayName: Email Verification - name: LeadList description: A list used to store leads x-displayName: Lead List - name: InboxPlacementTest description: An inbox placement test x-displayName: Inbox Placement Test - name: InboxPlacementAnalytics description: Analytics data for individual emails in inbox placement tests x-displayName: Inbox Placement Analytics - name: InboxPlacementBlacklist&SpamAssassinReport description: Report data for an inbox placement test x-displayName: Inbox Placement Blacklist & SpamAssassin Report - name: APIKey description: API Key x-displayName: API Key - name: AccountCampaignMapping description: Account Campaign Mapping x-displayName: Account Campaign Mapping - name: Lead description: A lead entity representing an individual lead x-displayName: Lead - name: BackgroundJob description: A background job that can be used to perform long-running tasks x-displayName: Background Job - name: CustomTag description: >- A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns. x-displayName: Custom Tag - name: CustomTagMapping description: >- This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (`tag_id` field) with the email account (`resource_id` field). You can use it to see which tag si connected to which resource. x-displayName: Custom Tag Mapping - name: BlockListEntry description: A blocked email or domain x-displayName: Block List Entry - name: LeadLabel description: A custom label for categorizing and managing leads x-displayName: Lead Label - name: Workspace description: A workspace entity representing a workspace x-displayName: Workspace - name: SuperSearchEnrichment description: >- An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it. x-displayName: SuperSearch Enrichment - name: WorkspaceGroupMember description: >- A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group. x-displayName: Workspace Group Member - name: WorkspaceMember description: A member of a workspace with associated user details x-displayName: Workspace Member - name: CampaignSubsequence description: A subsequence entity representing a follow-up sequence x-displayName: Campaign Subsequence - name: AuditLog description: Audit log records for tracking system activities x-displayName: Audit Log - name: Webhook description: A webhook subscription for receiving event notifications x-displayName: Webhook - name: WebhookEvent description: A webhook event that was sent or attempted to be sent x-displayName: Webhook Event - name: DFYEmailAccountOrder description: A Done-For-You email account order x-displayName: DFY Email Account Order - name: CustomPromptTemplate description: Custom prompt templates for creating custom prompts x-displayName: Custom Prompt Template - name: SalesFlow description: >- Manages how sales users view and interact with campaign and lead lists within the sales flow. x-displayName: Sales Flow - name: EmailTemplate description: A campaign email template x-displayName: Email Template - name: WorkspaceBilling description: Workspace Billing x-displayName: Workspace Billing - name: CRMActions description: CRM related actions x-displayName: CRM Actions paths: /api/v2/leads/move: post: tags: - Lead summary: Move leads to a campaign or list description: >- 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` operationId: moveLeads requestBody: content: application/json: schema: type: object properties: search: type: string description: >- A search string to search the leads against - can be First Name, Last Name, or Email example: John Doe filter: type: string x-enumDescriptions: FILTER_VAL_CONTACTED: Filter for contacted leads FILTER_VAL_NOT_CONTACTED: Filter for not contacted leads FILTER_VAL_COMPLETED: Filter for completed leads FILTER_VAL_UNSUBSCRIBED: Filter for unsubscribed leads FILTER_VAL_ACTIVE: Filter for active leads FILTER_LEAD_INTERESTED: Filter for interested leads FILTER_LEAD_NOT_INTERESTED: Filter for not interested leads FILTER_LEAD_MEETING_BOOKED: Filter for leads with meeting booked FILTER_LEAD_MEETING_COMPLETED: Filter for leads with meeting completed FILTER_LEAD_CLOSED: Filter for closed leads FILTER_LEAD_OUT_OF_OFFICE: Filter for leads out of office FILTER_LEAD_WRONG_PERSON: Filter for wrong person leads FILTER_LEAD_LOST: Filter for lost leads FILTER_LEAD_NO_SHOW: Filter for no show leads FILTER_LEAD_CUSTOM_LABEL_POSITIVE: Filter for leads with positive custom label FILTER_LEAD_CUSTOM_LABEL_NEGATIVE: Filter for leads with negative custom label FILTER_VAL_BOUNCED: Filter for bounced leads FILTER_VAL_SKIPPED: Filter for skipped leads FILTER_VAL_RISKY: Filter for risky leads FILTER_VAL_INVALID: Filter for invalid leads FILTER_VAL_VALID: Filter for valid leads FILTER_VAL_IN_SUBSEQUENCE: Filter for leads in subsequence FILTER_VAL_OPENED_NO_REPLY: Filter for leads with opened emails but no reply FILTER_VAL_COMPLETED_NO_REPLY: Filter for leads with completed sequence but no reply FILTER_VAL_NO_OPENS: Filter for leads with no opened emails FILTER_VAL_REPLIED: Filter for leads that replied FILTER_VAL_LINK_CLICKED: Filter for leads that clicked a link description: >- Filter criteria for leads. For custom lead labels, use the `interest_status` field. example: FILTER_VAL_CONTACTED campaign: type: string format: uuid description: Campaign ID to filter leads example: 019e18e2-9b9a-7ae7-a643-c22062035e92 list_id: type: string format: uuid description: List ID to filter leads example: 019e18e2-9b9a-7ae7-a643-c221e2cbb421 in_campaign: type: boolean description: Whether the lead is in a campaign example: true in_list: type: boolean description: Whether the lead is in a list example: true ids: type: array items: type: string format: uuid example: 019e18e2-a5e3-7b9f-b80c-2d21724ca362 description: >- 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: type: array items: type: object required: - actionType - values description: Smart view query to filter leads properties: actionType: type: string enum: - reply - email-open - last-contacted - link-click - lead-status - lead-status-change example: email-open values: type: object properties: occurrence-days: type: number example: 1 occurrence-count: type: object properties: condition: type: string enum: - more - less - equal example: more count: type: number example: 1 lead-status: type: object properties: status: type: number example: 1 condition: type: string enum: - is - is-not example: is example: actionType: email-open values: occurrence-days: 1 excluded_ids: type: array items: type: string format: uuid example: 019e18e2-9b9a-7ae7-a643-c223f81b2b84 description: Array of lead IDs to exclude contacts: type: array items: type: string format: email example: test@test.com description: Array of emails the leads needs to have to_campaign_id: type: string format: uuid description: The ID of the campaign to move the leads to. example: 019e18e2-a5e3-7b9f-b80c-2d226de3e628 to_list_id: type: string format: uuid description: The ID of the list to move the leads to. example: 019e18e2-a5e3-7b9f-b80c-2d23a6b21b96 ignore_resource_filter_clauses: type: boolean description: >- Whether to ignore saved lead-finder clauses for the source campaign/list when selecting leads to move. example: true check_duplicates_in_campaigns: type: boolean description: Whether to check duplicates in campaigns. example: true skip_leads_in_verification: type: boolean description: Whether to skip leads in verification. example: true limit: type: number description: The limit of the number of leads to move. example: 10 assigned_to: type: string format: uuid description: The ID of the user to assign the leads to. example: 019e18e2-a5e3-7b9f-b80c-2d2428f35188 esp_code: type: number enum: - 0 - 1 - 2 - 3 - 8 - 9 - 10 - 12 - 13 - 999 - 1000 x-enumDescriptions: '0': In Queue '1': Google '2': Microsoft '3': Zoho '8': AirMail '9': Yahoo '10': Yandex '12': Webde '13': Liberoit '999': Other '1000': Not Found description: The ESP code to move the leads for. example: 1 esg_code: type: string enum: - '0' - '1' - '2' - '3' - '4' - all - none x-enumDescriptions: '0': In Queue '1': Barracuda '2': Mimecast '3': Proofpoint '4': Cisco all: All none: None description: The ESG code to move the leads for. example: '1' copy_leads: type: boolean description: Whether to copy the leads. example: true check_duplicates: type: boolean description: Whether to check duplicates. example: true reset_interest_status: type: boolean description: >- 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: true responses: '200': description: The requested Background Job content: application/json: schema: $ref: '#/components/schemas/def-12' '401': description: >- This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked) content: application/json: schema: type: object properties: statusCode: type: number enum: - 401 example: 401 error: type: string enum: - Unauthorized example: Unauthorized message: type: string example: Missing Authorization header required: - statusCode - error - message '402': description: >- This request cannot be fulfilled because the workspace does not have an active paid plan content: application/json: schema: type: object properties: statusCode: type: number enum: - 402 example: 402 error: type: string enum: - Payment Required example: Payment Required message: type: string example: Workspace does not have an active paid plan required: - statusCode - error - message '404': description: The requested resource was not found content: application/json: schema: type: object properties: statusCode: type: number enum: - 404 example: 404 error: type: string enum: - Not Found example: Not Found message: type: string example: Resource not found required: - statusCode - error - message '429': description: >- You have exceeded the rate limit. Please check the rate limit docs for more information. content: application/json: schema: type: object properties: statusCode: type: number enum: - 429 example: 429 error: type: string enum: - Too Many Requests example: Too Many Requests message: type: string example: Rate limit exceeded required: - statusCode - error - message components: schemas: def-12: title: Background Job description: A background job that can be used to perform long-running tasks x-tags: - Schemas - BackgroundJob type: object properties: id: type: string description: Unique identifier for the background job readOnly: true example: 675266e304a8e55b17f0228b workspace_id: type: string description: Workspace ID readOnly: true format: uuid example: 019e18e2-791d-7da7-9459-942f29778e95 user_id: type: - 'null' - string description: The id of the user that triggered the action that created the job readOnly: true format: uuid example: 019e18e2-791d-7da7-9459-94304e5234a6 type: type: string description: Type of background job enum: - move-leads - import-leads - export-leads - update-warmup-accounts - rename-variable x-enumDescriptions: move-leads: Move Leads import-leads: Import Leads export-leads: Export Leads update-warmup-accounts: Update Warmup Accounts rename-variable: Rename Variable example: move-leads entity_id: type: - 'null' - string description: The id of the entity that the job is related to format: uuid example: 019e18e2-791d-7da7-9459-9431dc674a9f entity_type: type: string description: Type of entity enum: - list - campaign - workspace x-enumDescriptions: list: The entity is a lead list campaign: The entity is a campaign workspace: The entity is a workspace example: list data: type: object description: >- Data about the job, used to store any additional information we need to process the job properties: moved_lead_emails: type: array description: >- For `move-leads` jobs, up to the first 10,000 email addresses of leads that actually moved or copied to the destination after all filters were applied. Use `moved_leads` for the full count. items: type: string format: email example: jane@example.com example: - jane@example.com - john@example.com additionalProperties: true progress: type: number description: Progress of the job as a percentage (from 0 to 100) minimum: 0 maximum: 100 example: 0 status: type: string description: Job status enum: - pending - in-progress - success - failed x-enumDescriptions: pending: The background job is waiting in the queue to be processed in-progress: The background job is being processed success: The background job has been successfully processed failed: The background job has failed example: pending created_at: type: string description: Timestamp when the job was created example: '2026-05-11T21:12:35.869Z' updated_at: type: string description: Timestamp when the job was last updated example: '2026-05-11T21:12:35.869Z' required: - id - workspace_id - type - progress - status - created_at - updated_at additionalProperties: false securitySchemes: ApiKeyAuth: type: http scheme: bearer ````