Notifications

Notification subscriptions control which users receive alerts for resource-level events (errors, status changes, completions) on flows, connections, integrations, and syncs. Each subscription routes alerts to the email of the subscribed user.

Subscriptions are account-scoped — an account admin can manage subscriptions on behalf of any user, not just their own.

Notification schema

List notification subscriptions

get

/v1/notifications

Returns notification subscriptions for flows, connections, integrations, and syncs in the account. Without the users=all query parameter, the response is scoped to the caller's own subscriptions. With users=all, every user's subscriptions in the account are returned.

Returns an empty response when the caller has no subscriptions in the current scope. With users=all, an empty array is returned only in accounts with zero subscriptions across all users.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usersstring · enumOptional

When set to all, returns subscriptions for every user in the account. When omitted, returns only the caller's own subscriptions.

Possible values:

Responses

200

Array of notification subscriptions.

application/json

A notification subscription linking a user email to a single resource (flow, connection, integration, or sync). When the resource emits an alert (error, state change, etc.), the subscribed user is notified.

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

typestring · enumRequired

Which resource class this subscription targets. Implies which of _flowId / _connectionId / _integrationId / _syncId is populated.

Possible values:

_flowIdstring · objectIdOptional

Flow id when type: flow.

Example: 69497fc443fc1f9a03d31bd9

_connectionIdstring · objectIdOptional

Connection id when type: connection.

Example: 5e5eb06fdd83ed4f8206a4ea

_integrationIdstring · objectIdOptional

Integration id when type: integration.

Example: 5d2c5a8f3e9b1c4a7f6d2e80

_syncIdstring · objectIdOptional

Sync id when type: sync.

Example: 69e7549b0f8b6cd703e5d3b2

204

Caller has no subscriptions in the current scope (default scope when users=all is omitted). Not the same as 200 with [].

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/notifications

GET /v1/notifications HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "612e68884d644e604724250a",
    "type": "connection",
    "_connectionId": "5e5eb06fdd83ed4f8206a4ea",
    "lastModified": "2021-08-31T17:36:09.092Z",
    "subscribedByUser": {
      "name": "James Roth",
      "email": "[e-mail]"
    }
  },
  {
    "_id": "698abc1234567890abcdef01",
    "type": "flow",
    "_flowId": "69497fc443fc1f9a03d31bd9",
    "lastModified": "2026-04-01T12:00:00.000Z",
    "subscribedByUser": {
      "name": "Jane Doe",
      "email": "[e-mail]"
    }
  },
  {
    "_id": "69e754caae7bf0aeb0f69f3a",
    "type": "sync",
    "_syncId": "69e7549b0f8b6cd703e5d3b2",
    "lastModified": "2026-04-21T10:43:22.077Z",
    "subscribedByUser": {
      "name": "Bhavik Shah",
      "email": "[e-mail]"
    }
  }
]

Subscribe / unsubscribe users to resource notifications

put

/v1/notifications

Upserts a batch of notification subscriptions. Each item targets exactly one resource (_flowId, _connectionId, or _integrationId) plus a subscribedByUserEmail. subscribed: true creates (or keeps) the subscription; subscribed: false removes it.

Returns a parallel array of per-item results — one entry per request item, in the same order. Each result carries statusCode (201 when a subscription was created, 200 when updated or removed, 422 when a referenced resource doesn't exist) plus an errors[] array on failures. An empty request body returns an empty array.

The body is a bare array (maximum 500 items). Each item must carry exactly one of _flowId / _connectionId / _integrationId / _syncId. The response is a per-item status array; referencing a non-existent resource fails that item with statusCode: 422 but does not fail the whole request.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Bodyone of[]

Bare array (no wrapping envelope) of upsert items. Each item targets a single resource and flips subscription state on or off for one user.

anyOptional

or

anyOptional

or

anyOptional

or

anyOptional

Responses

200

Per-item result array (parallel to the request). Each entry is {statusCode, errors?} — statusCode: 200 on success, or a non-200 status with an errors[] array on per-item failures. Overall HTTP is still 200 even when individual items fail.

application/json

Per-item upsert result.

statusCodeintegerOptional

Per-item outcome: 200 when the subscription was created, updated, or left unchanged; 422 when the referenced resource doesn't exist (details in errors[]).

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

put/v1/notifications

PUT /v1/notifications HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 101

[
  {
    "_flowId": "69497fc443fc1f9a03d31bd9",
    "subscribed": true,
    "subscribedByUserEmail": "[e-mail]"
  }
]

[
  {
    "statusCode": 200
  },
  {
    "statusCode": 200
  }
]