LEleadfeeder
Lists
v1

Create Batch Add to List Job

Changed on

Schedule an asynchronous job that adds members to 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. You need permission to change the list's members, and it can't be a read-only list, such as a revealed, CRM or custom feed list. 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. A list holds at most 1,000,000 members. To remove members, use POST /v1/lists/batch-remove-from-list-jobs — adding and removing are separate jobs.

Returns 202 Accepted with a job handle. Poll GET /v1/lists/batch-add-to-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: Adding members to a list does not consume credits.

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

post/v1/lists/batch-add-to-list-jobs

Request

  • Base URL
    https://api.leadfeeder.com
  • URL
    https://api.leadfeeder.com/v1/lists/batch-add-to-list-jobs
  • Auth
    • API key in header X-Api-Key
    • or OAuth 2
      Authorization code: https://api.leadfeeder.com/v1/oauth/authorize
      Token URL: https://api.leadfeeder.com/v1/oauth/token scopes: lists:write

Query parameters

account_idstring required

The Leadfeeder Account ID. The Account ID can be retrieved using the List Accounts endpoint.

Request body

Example request

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

Response

Batch add-to-list job accepted and enqueued

Example response

{
  "data": {
    "attributes": {
      "completed_at": "2026-05-13T12:00:18Z",
      "configuration": {
        "advanced_search": {
          "excluded_company_ids": [
            "651713"
          ],
          "filters": {
            "items": [
              {
                "field": "country_code",
                "operator": "in",
                "type": "filter",
                "value": [
                  "DE"
                ]
              },
              {
                "field": "employee_count",
                "operator": "in_range",
                "type": "filter",
                "value": {
                  "gte": 50
                }
              }
            ],
            "operator": "and",
            "type": "group"
          },
          "page": {
            "size": 1000
          },
          "sort": {
            "direction": "desc",
            "field": "employee_count"
          }
        },
        "items": [
          {
            "id": "159001425",
            "type": "company"
          }
        ],
        "list_id": "company_123"
      },
      "created_at": "2026-05-13T12:00:00Z",
      "errors": [
        {
          "code": "job_failed",
          "title": "External contact data provider timeout"
        }
      ],
      "results": [
        {
          "id": "159001425",
          "status": "added",
          "type": "company"
        }
      ],
      "status": "running",
      "summary": {
        "added": 1,
        "already_present": 1,
        "list_size_after": 52,
        "list_size_before": 51
      }
    },
    "id": "job_550e8400-e29b-41d4-a716-446655440000",
    "type": "batch_add_to_list_job"
  },
  "meta": {
    "request_id": "cf054205-dd8c-4473-8689-07c30fe0789f"
  }
}

Changes

  • 8e37aaf0ccadRevision changes
    • info

      removed the scope_mismatch enum value from the //// response property for the response status

  • 1344fb600ac2Revision changes
    • breaking

      the ////// response property's minItems was decreased from 1 to 0 for the response status

    • breaking

      the ///////// response property's minItems was decreased from 1 to 0 for the response status