Create Batch Remove from List Job

Schedule an asynchronous job that removes members from a single list. The target list is identified by data.attributes.list_id in the request body; its prefix (company_ or contact_) determines whether company or contact references are accepted. The members are supplied either as an explicit data.attributes.items array (up to 100 items per request), or — for company lists only — as a data.attributes.advanced_search selection that is resolved into the list's matching companies (up to 100,000) when the job runs. To add members, use POST /v1/lists/batch-add-to-list-jobs — adding and removing are separate jobs.

When the job is created, the list is only checked for being one you can read. If you may not change its members, or it is a read-only list, such as a revealed, CRM or custom feed list, the job fails when it removes members from it.

Returns 202 Accepted with a job handle. Poll GET /v1/lists/batch-remove-from-list-jobs/{job_id} to observe progress and the outcome: per-item results plus summary counts for items jobs, summary counts only for jobs created from a search selection.

Credit Note: Removing members from a list does not consume credits.

INFO

Requires the lists:write OAuth2 scope.

Request

Authorization

API Key

Add parameter in header

X-Api-Key

Example:

X-Api-Key: ********************

Query Params

Body Params application/jsonRequired

Examples

Remove companies from a company listRemove contacts from a contact listRemove the companies matching an advanced search from a company list

{
    "data": {
        "attributes": {
            "items": [
                {
                    "id": "159001425",
                    "type": "company"
                },
                {
                    "id": "159001426",
                    "type": "company"
                }
            ],
            "list_id": "company_123"
        },
        "type": "batch_remove_from_list_job"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢202Accepted

application/json

Batch remove-from-list job accepted and enqueued

Bodyapplication/json

Example

{
    "data": {
        "attributes": {
            "configuration": {
                "items": [
                    {
                        "id": "3170656125",
                        "type": "contact"
                    },
                    {
                        "id": "3219787635",
                        "type": "contact"
                    }
                ],
                "list_id": "contact_456"
            },
            "created_at": "2026-05-13T12:00:00Z",
            "status": "running"
        },
        "id": "job_7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "type": "batch_remove_from_list_job"
    },
    "meta": {
        "request_id": "cf054205-dd8c-4473-8689-07c30fe0789f"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠422Parameter Error

🟠429

🔴500Server Error

🔴504Gateway Timeout