Bulk Untag Leads

Remove tags from many leads at once.

POSThttps://api.foxreach.io/api/v1/leads/bulk/untag

Requires an API key with the write scope.

Up to 1,000 selected leads run inside the request and the job comes back completed (200). More than that is queued: the response is 202 with a pending job; poll Get Job until it is completed.

Tags that a lead does not carry are ignored. The tags themselves are kept.

Body Parameters#

leadIdsstring[]body

Lead IDs, up to 50,000. Send this or filter, not both.

filterobjectbody

Select leads by filter instead. Keys: search, status, tags (comma separated; a lead must carry all of them), provider, interestStatus, labelId. Matches at most 50,000 leads, newest first.

tagsstring[]bodyrequired

Tag names to remove, 1 to 50.

Response#

dataobject

The job. See Get Job for every field.

Show Job object

idstring

Job identifier.

typestring

lead_bulk.

statusstring

completed when the call finished the work (200), pending when it was queued (202).

totalItemsinteger

Leads selected.

resultobject

{ "updated": 120 }: how many of the selected leads in your workspace were processed.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `write`
`422`	Neither or both of `leadIds` and `filter` were sent, or `tags` is empty

Rate Limit#

100 requests per minute, shared by every bulk call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (bulk).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Request

cURL

curl -X POST "https://api.foxreach.io/api/v1/leads/bulk/untag" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"leadIds": ["cmlead1"], "tags": ["acme"]}'

Python SDK

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
job = client.leads.bulk_untag(["acme"], lead_ids=["cmlead1"])

TypeScript SDK

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const job = await client.leads.bulkUntag({ tags: ["acme"], leadIds: ["cmlead1"] });

Response

JSON

{
  "data": {
    "id": "cmjob902",
    "type": "lead_bulk",
    "status": "completed",
    "progress": 100,
    "totalItems": 1,
    "completedItems": 1,
    "result": { "updated": 1 },
    "error": null,
    "startedAt": "2026-11-04T09:00:00",
    "completedAt": "2026-11-04T09:00:00",
    "createdAt": "2026-11-04T09:00:00"
  }
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026