# Untag Contacts

Removes manual tags from a selection of contacts, like the bulk action of the contact search. Without confirm it only previews pair counts and known effects. With confirm=true, pairs without the tag are skipped, up to 200 changed pairs are written at once and more are queued in the background without a completion receipt; repeat the preview to see what is still pending. Removal may alter queued messages and automations; it does not unsubscribe. For one contact use untag-contact; to assign use tag-contacts.

## Input schema:

```json
{
  "type": "object",
  "properties": {
    "contactIds": {
      "type": "array",
      "description": "Distinct contact IDs of the whole selection (1-500), not only one search page",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 500,
      "uniqueItems": true
    },
    "tagIds": {
      "type": "array",
      "description": "Existing manual tag IDs (1-20) to remove",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "minItems": 1,
      "maxItems": 20,
      "uniqueItems": true
    },
    "confirm": {
      "type": "boolean",
      "description": "False returns the preview without changes; true only after the user approved that preview",
      "default": false
    },
    "accountId": {
      "type": [
        "null",
        "integer"
      ],
      "description": "User ID of the account; omit for the account of the access token",
      "default": null,
      "minimum": 1
    }
  },
  "required": [
    "contactIds",
    "tagIds"
  ],
  "additionalProperties": false
}
```

## Output schema:

```json
{
  "type": "object",
  "required": [
    "accountId",
    "status",
    "contactCount",
    "pairCount",
    "changed",
    "unchanged",
    "pending",
    "failed",
    "failures",
    "knownEffects"
  ],
  "properties": {
    "accountId": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "preview",
        "completed",
        "queued"
      ]
    },
    "contactCount": {
      "type": "integer"
    },
    "pairCount": {
      "type": "integer"
    },
    "changed": {
      "type": "integer"
    },
    "unchanged": {
      "type": "integer"
    },
    "pending": {
      "type": "integer"
    },
    "failed": {
      "type": "integer"
    },
    "failures": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "contactId",
          "tagId",
          "reason"
        ],
        "properties": {
          "contactId": {
            "type": "integer"
          },
          "tagId": {
            "type": "integer"
          },
          "reason": {
            "type": "string"
          }
        }
      }
    },
    "knownEffects": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
```

