SCscalekit
Triggers

Subscribe several accounts to a trigger

Changed on

Subscribes many connected accounts to one trigger with one filter, and reports what happened to each account separately. Use this instead of repeating the single-account call when onboarding a connection that already has many accounts. The call is best-effort rather than all-or-nothing: a refused account does not undo one that succeeded, because refusals here are ordinary rather than exceptional — an account may hold a revoked credential, lack a scope, or already carry this exact filter. Each result names its own outcome, and a refusal names its remedy. Retrying the whole request is safe: an account subscribed by an earlier attempt comes back as already subscribed rather than as an error. A connection-scoped trigger is subscribed on the connection itself rather than per account: send an empty connected_account_ids for it, and the one subscription comes back as a single result with an empty connected_account_id.

post/api/v1/connections/{connection_id}/trigger-subscriptions:batchCreate

Request

Path parameters

connection_idstring required

ID of the connection, in this environment. Up to 64 characters.

Request body

configobject

Filter values applied to every account in the batch, keyed by the trigger's config_fields keys. Each account gets its own subscription with these values, so subscribing the same accounts again with different values adds subscriptions rather than replacing these. Invalid values refuse the whole request.

connected_account_idsstring[]

Connected accounts to subscribe, at most 100 — one page of the account picker — with no repeats. Which to send depends on the trigger's delivery_scope, from ListAvailableTriggers. For an ACCOUNT-scoped trigger, list at least one account; an empty list refuses the whole request with a 400. For a CONNECTION-scoped trigger, send an empty list: the trigger is subscribed once, on the connection itself, and results holds exactly one result, with an empty connected_account_id. Naming accounts for a connection-scoped trigger refuses each of them (REFUSED), since that trigger is not subscribed per account.

interval_secondsinteger

Polling interval in seconds, for a polled trigger only, applied to every account in the batch. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds, or any value for a webhook trigger, refuses the whole request. A large batch of polled subscriptions shares the environment's polling budget, so the subscriptions can run slower than requested; effective_interval_seconds on each subscription shows the interval it runs at.

trigger_namestring required

Name of the trigger to subscribe to, as returned in the name field of ListAvailableTriggers. Up to 128 characters.

Example request

{
  "config": {
    "channel": "C0123456789"
  },
  "connected_account_ids": [
    "ca_123456789012345",
    "ca_123456789012346"
  ],
  "interval_seconds": 300,
  "trigger_name": "slack_message_posted"
}

Response

One result per requested account, in request order, and the number of subscriptions this call created. Individual accounts can still be REFUSED, NOT_FOUND or FAILED

created_countinteger

How many subscriptions this call created. Excludes accounts that were already subscribed.

Example response

{
  "created_count": 98,
  "results": [
    {
      "connected_account_id": "ca_123456789012345",
      "reason": "connected account not found",
      "subscription": {
        "config": {
          "channel": "C0123456789"
        },
        "connected_account_id": "ca_123456789012345",
        "connected_account_identifier": "user_123",
        "connection_id": "conn_123456789012345",
        "effective_interval_seconds": 60,
        "id": "trgs_123456789012345",
        "poll_state": {
          "last_error": "The provider is rate-limiting requests. Polling resumes automatically after a backoff."
        },
        "provider": "slack",
        "requested_interval_seconds": 60,
        "trigger_name": "slack_message_posted"
      }
    }
  ]
}

Changes