Bulk Tag Subscribers

convertkit.bulk_tag_subscribers

ActionEmailconnection required

Calls the ConvertKit API with the connection's credentials.

Apply many tag-to-subscriber pairs in one call, reporting Kit's per-pair failures for a batch it processed synchronously.

Connection

Required: Yes — the node will not save without one
Auth type: API key
Providers: ConvertKit
Secret shape: the v4 API key, or {"api_key": "…"}, or {"access_token": "…"} for OAuth
Config it needs: base_url
Resolved by: config.connection_id, else node.connection_id

2 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
taggings The pairs to apply: a JSON array of objects with 'tag_id' and 'subscriber_id'.	array	Yes	—	array of object	[{"subscriber_id":1258,"tag_id":218}]
callback_url Webhook Kit posts the outcome to when the batch is too large to process synchronously (more than 100 items).	string	No	—	url format	—

Every value below is the contract’s own example or default — nothing invented.

{
  "taggings": [
    {
      "subscriber_id": 1258,
      "tag_id": 218
    }
  ]
}

One shape.

Field	Type	Example
items The records Kit created or updated, when it answered synchronously.	array	—
failures One entry per item Kit refused, each carrying its own 'errors' list and the item that caused them.	array	—
succeeded How many items Kit reported as written.	number	—
failed How many items Kit refused.	number	—
requested How many items this node sent.	number	—
queued True when the batch was larger than Kit's synchronous limit of 100, so Kit accepted it for background processing and returned no per-item result; the outcome arrives at 'callback_url'.	boolean	—

{
  "failed": 0,
  "failures": [],
  "items": [],
  "queued": false,
  "requested": 0,
  "succeeded": 0
}

Every subscriber named must already exist. Kit tags 100 pairs or fewer synchronously and returns each failure; a larger batch comes back with 'queued' true and no per-pair result.

In a technical demo we add the ConvertKit connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.