API Reference

Merge audiences

Unions every source audience membership into the target, removes overlapping memberships, and permanently deletes the source audience documents in one transaction. The path audienceId is the target. The target keeps its name, type, folder, and position. Campaign-link validation runs before any mutation; a linked source returns 409 and changes nothing. There is intentionally no potentially stale preflight flag. After confirming the exact destructive target and sources, call once. On 409, do not retry; re-read state and choose another source or use lead move/copy.

POST/v1/accounts/{accountGroupId}/audiences/{audienceId}/merge

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

sourceAudienceIds

Type: array<string>

Request field for source audience ids.

Required

Responses

200

Audiences merged

Schema: AudienceMergeSuccessResponse

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

An audience is active, campaign-linked, or changed concurrently

Schema: ErrorResponse

422

The target is also present in the source audience list

Schema: ErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

Response examples

200 Example JSONAudienceMergeSuccessResponse

{
    "success": true,
    "data": {
        "targetAudience": {
            "id": "507f1f77bcf86cd799439011",
            "name": "Avery Stone",
            "type": "linkedin_search",
            "description": "string",
            "folderId": "507f1f77bcf86cd799439011",
            "position": 25,
            "prospectCount": 25,
            "createdAt": "string",
            "updatedAt": "string"
        },
        "mergedAudienceIds": [
            "string"
        ],
        "mergedLeadCount": 25,
        "duplicateMembershipCount": 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"
}