---
title: "Create Batch Remove from List Job"
method: POST
path: "/v1/lists/batch-remove-from-list-jobs"
tags: ["Lists", "v1"]
---

# Create Batch Remove from List Job

`POST /v1/lists/batch-remove-from-list-jobs`

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; the list's `list_type` 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 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.

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 `advanced_search` jobs.

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

:::info
Requires the `lists:write` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required

## Request body

- object — Request body for creating a batch remove-from-list job. The target list is identified by `list_id` inside `data.attributes` — the list's `list_type` (company or contact) determines which kind of references are valid. Supplying references whose type does not match the list scope yields `422 invalid_parameter` (scope mismatch). The members are supplied either as an explicit `items` array, or — for company lists only — as an `advanced_search` selection that is resolved into companies when the job runs. Exactly one of `items` and `advanced_search` must be supplied.
  - `data` object, required
    - `type` string — The job resource type. Optional — the operation is fixed by the endpoint, so a value supplied here is ignored.
    - `attributes` union, required
      - object
        - `list_id` string, required — The scope-prefixed target list identifier (e.g. `company_123` or `contact_456`). The list's `list_type` determines which kind of references may appear in `items`.
        - `items` object[], required — The company or contact references to remove from the list. A maximum of 100 items may be supplied. Every item's `type` must match the target list's `list_type` (company list → `company`, contact list → `contact`). Mutually exclusive with `advanced_search`.
          - `type` 'company' | 'contact', required — The entity type of the reference — must match the target list's `list_type`.
          - `id` string, required — The Dealfront entity ID.
        - `advanced_search` object — Remove every company matching an advanced search from the list, instead of listing companies one by one in `items`. Use the same `filters`, `sort` and `page` you would when browsing companies; all matching companies (up to 100,000) are removed when the job runs, and matches that are not on the list leave it unchanged. This is only available for company lists — it can't be used on a contact list or together with `items`. The outcome is reported as `summary` counts rather than a per-company `results` list.
          - `filters` object, required — Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`).
            - `type` 'group', required — Indicates this is the root filter group.
            - `operator` 'and' | 'or', required — The logical operator combining the items.
            - `items` CompaniesAdvancedSearchFilterItem[], required — Nested filter conditions or sub-groups. Each item is either a `filter` or a nested `group`.
              - …
          - `sort` object — Ordering applied to the matching companies. Omit to use the default ordering.
            - `field` string — Comma-separated list of company attributes to sort by, applied in order (e.g. `employee_count,name`). Allowed values: `relevance`, `name`, `employee_count`, `revenue`, `founded_year`. Unknown values are rejected with `invalid_parameter`.
            - `direction` 'asc' | 'desc' — Sort direction. Defaults to `asc`.
          - `page` object — Bounds how many of the matching companies are selected.
            - `size` integer — Maximum number of matching companies to select, taken in `sort` order. Omit to select every match, up to the endpoint's per-job maximum.
          - `excluded_company_ids` string[] — Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`.
      - object
        - `list_id` string, required — The scope-prefixed target list identifier (e.g. `company_123` or `contact_456`). The list's `list_type` determines which kind of references may appear in `items`.
        - `items` object[] — The company or contact references to remove from the list. A maximum of 100 items may be supplied. Every item's `type` must match the target list's `list_type` (company list → `company`, contact list → `contact`). Mutually exclusive with `advanced_search`.
          - `type` 'company' | 'contact', required — The entity type of the reference — must match the target list's `list_type`.
          - `id` string, required — The Dealfront entity ID.
        - `advanced_search` object, required — Remove every company matching an advanced search from the list, instead of listing companies one by one in `items`. Use the same `filters`, `sort` and `page` you would when browsing companies; all matching companies (up to 100,000) are removed when the job runs, and matches that are not on the list leave it unchanged. This is only available for company lists — it can't be used on a contact list or together with `items`. The outcome is reported as `summary` counts rather than a per-company `results` list.
          - `filters` object, required — Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`).
            - `type` 'group', required — Indicates this is the root filter group.
            - `operator` 'and' | 'or', required — The logical operator combining the items.
            - `items` CompaniesAdvancedSearchFilterItem[], required — Nested filter conditions or sub-groups. Each item is either a `filter` or a nested `group`.
              - …
          - `sort` object — Ordering applied to the matching companies. Omit to use the default ordering.
            - `field` string — Comma-separated list of company attributes to sort by, applied in order (e.g. `employee_count,name`). Allowed values: `relevance`, `name`, `employee_count`, `revenue`, `founded_year`. Unknown values are rejected with `invalid_parameter`.
            - `direction` 'asc' | 'desc' — Sort direction. Defaults to `asc`.
          - `page` object — Bounds how many of the matching companies are selected.
            - `size` integer — Maximum number of matching companies to select, taken in `sort` order. Omit to select every match, up to the endpoint's per-job maximum.
          - `excluded_company_ids` string[] — Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`.

## Response `202`

Batch remove-from-list job accepted and enqueued

- object
  - `data` BatchRemoveFromListJobV1, required
    - `type` string, required
    - `id` string, required — Unique job identifier
    - `attributes` object, required
      - `status` 'running' | 'completed' | 'failed', required — Current status of the job
      - `configuration` union, required — Echoed request configuration. Present at every status, from the moment the job is created. Carries the `items` array or the `advanced_search` selection the job was created with — exactly one of the two.
        - object
          - `list_id` string, required — The scope-prefixed list identifier the job operates on (e.g. `company_123` or `contact_456`).
          - `items` object[], required — The references supplied in the originating request.
            - `type` 'company' | 'contact', required — The entity type (e.g. `company` or `contact`).
            - `id` string, required — The Dealfront entity ID.
          - `advanced_search` object — The advanced-search selection supplied in the originating request.
            - `filters` object, required — Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`).
              - …
            - `sort` object — Ordering applied to the matching companies. Omit to use the default ordering.
              - …
            - `page` object — Bounds how many of the matching companies are selected.
              - …
            - `excluded_company_ids` string[] — Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`.
        - object
          - `list_id` string, required — The scope-prefixed list identifier the job operates on (e.g. `company_123` or `contact_456`).
          - `items` object[] — The references supplied in the originating request.
            - `type` 'company' | 'contact', required — The entity type (e.g. `company` or `contact`).
            - `id` string, required — The Dealfront entity ID.
          - `advanced_search` object, required — The advanced-search selection supplied in the originating request.
            - `filters` object, required — Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`).
              - …
            - `sort` object — Ordering applied to the matching companies. Omit to use the default ordering.
              - …
            - `page` object — Bounds how many of the matching companies are selected.
              - …
            - `excluded_company_ids` string[] — Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`.
      - `results` object[] — Per-item outcome of the remove job. Present only when `status` is `completed` and the job was created with an explicit `items` array — a job created from an `advanced_search` selection reports `summary` counts only.
        - `id` string, required — The Dealfront company or contact ID that was processed.
        - `type` 'company' | 'contact', required — The kind of entity this result item refers to.
        - `status` 'removed' | 'not_present' | 'not_found' | 'scope_mismatch', required — Indicative, best-effort status for this item, derived from the underlying backend system. It is not a guaranteed-exact per-item outcome: an item that was not applied may be reported with an approximate status, because the backend cannot always distinguish between cases (for example, `not_present` from `not_found`).
      - `summary` object — Counts of items by outcome, plus the list size after the job applied. Present only when `status` is `completed`. The outcome counts are best-effort: they aggregate the indicative per-item statuses and are not a guaranteed-exact classification.
        - `removed` integer — Number of members removed. For a job created from an `advanced_search` selection, every company in the selection is counted here.
        - `not_present` integer — Number of members not in the list (remove no-op).
        - `not_found` integer — Number of referenced entities that could not be found.
        - `scope_mismatch` integer — Number of references whose type did not match the list scope.
        - `failed_count` integer — Total number of items that did not complete successfully (sum of `not_found` and `scope_mismatch`).
        - `list_size_after` integer — Number of members on the list after the job applied.
      - `errors` object[] — Present only when `status` is `failed`.
        - `code` string, required — Machine-readable error code
        - `title` string, required — Human-readable error description
      - `created_at` string, date-time, required — When the job was created.
      - `completed_at` string, date-time, nullable — When the job finished. Present only once the job has reached `completed` or `failed`.
  - `meta` object, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Malformed request envelope — the body is missing the required `data.attributes` object.
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `404` — List not found or not accessible in this account. Returned synchronously, before any job is created.
- `422` — Well-formed envelope that fails domain validation — scope mismatch (item `type` does not match the list's `list_type`), empty `items`, more than 100 items, both `items` and `advanced_search` supplied, or an `advanced_search` selection on a contact list or without `filters`. Removals cannot exceed list capacity, so there is no `list_capacity_exceeded` on this endpoint.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)