API Reference

Move leads between audiences

The path audienceId is the source and body.targetAudienceId is the target. Adds the selected source memberships to the target, then removes them from the source in one transaction. body.leadIds must be prospect IDs returned by the source audience's prospect-list route. IDs not present in the source are ignored. Use the copy operation when the source memberships must remain.

POST/v1/accounts/{accountGroupId}/audiences/{audienceId}/move-leads

Move constraints

Source and target audiences must belong to the selected account group, must be distinct, and cannot be actively populated by prospecting jobs.

Integration notes

Required API permission

audiences:write.

Prerequisites

integration_api_key, account_group_access.

Idempotency

not supported; check the current resource state before retrying this request.

Parameters

accountGroupIdPath

Type: string

Account group ID that scopes the request.

Required

audienceIdPath

Type: string

Audience ID that identifies the list or folder target.

Required

Request body

Required

Optional

Content types

application/json

Schema

object

Fields

targetAudienceId

Type: string

Audience ID that receives the selected leads.

Required

leadIds

Type: array<string>

Lead IDs to include in the requested operation.

Required

Responses

200

Leads moved

Schema: AudienceLeadMoveSuccessResponse

400

Request validation failed

Schema: ValidationErrorResponse

401

Invalid or missing API key

Schema: ErrorResponse

403

Missing required permission

Schema: ErrorResponse

404

Resource not found

Schema: ErrorResponse

409

One of the audiences is still being populated by an active prospecting job (AUDIENCE_NOT_READY)

Schema: ErrorResponse

422

Lead move failed validation

Schema: ErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

Response examples

200 Example JSONAudienceLeadMoveSuccessResponse

{
    "success": true,
    "data": {
        "sourceAudience": {
            "id": "507f1f77bcf86cd799439011",
            "name": "Avery Stone",
            "type": "linkedin_search",
            "description": "string",
            "folderId": "507f1f77bcf86cd799439011",
            "position": 25,
            "prospectCount": 25,
            "createdAt": "string",
            "updatedAt": "string"
        },
        "targetAudience": {
            "id": "507f1f77bcf86cd799439011",
            "name": "Avery Stone",
            "type": "linkedin_search",
            "description": "string",
            "folderId": "507f1f77bcf86cd799439011",
            "position": 25,
            "prospectCount": 25,
            "createdAt": "string",
            "updatedAt": "string"
        },
        "movedCount": 25
    },
    "error": null,
    "traceId": "507f1f77bcf86cd799439011"
}

400 Example JSONValidationErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

401 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

403 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

404 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

409 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

422 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

429 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

500 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}