Bulk Create Subscribers

convertkit.bulk_create_subscribers

ActionEmailconnection required

Calls the ConvertKit API with the connection's credentials.

Create many subscribers in one call, reporting Kit's per-item 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
subscribers The subscribers to create: a list of objects with 'email_address' and optional 'first_name' and 'state', or a list of bare addresses.	array	Yes	—	array of object	[{"email_address":"alice@example.com","first_name":"Alice"}]
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.

{
  "subscribers": [
    {
      "email_address": "alice@example.com",
      "first_name": "Alice"
    }
  ]
}

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
}

Kit processes 100 subscribers or fewer synchronously and returns each failure; a larger batch comes back with 'queued' true and no per-item result, so the run must not treat it as complete.

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.