# Tag Contacts

Assigns existing manual tags to 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 already tagged 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, and do not confirm again before it shows none, or queued pairs are tagged twice. Assigning tags may start real messages and automations. For one contact use tag-contact; to remove use untag-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); tags are never created",
      "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"
      }
    }
  }
}
```

