Skip to content

List Notifications API

The List Notifications API lets a developer retrieve every notification subscription in one call, including its delivery channel, subscribed event types, enabled state, and most recent test result. Use GET /v1/notifications/ when you need an inventory before creating, updating, testing, or deleting a subscription, or when you need to audit which subscriptions are active for a profile.

List Notifications API overview and when to use it

List notification subscriptions with a single GET request to /v1/notifications/. The trailing slash is part of the documented path and should be preserved exactly. This operation is the right starting point when you need to discover existing subscriptions before deciding whether to create a new one, inspect an existing one, or check whether a subscription has been tested successfully. Because the response returns the full subscription objects, you can audit channel, profile scope, event coverage, and enabled state without making a separate call per subscription.

Authorization with the x-access-key header

Authorization uses the x-access-key header, shown in the source as accessKey in the header with a token value. Send the header on the GET request and do not add undocumented query parameters, path parameters, or a request body. The source documents no request parameters beyond this header, so any filtering by profile, channel, or event type must happen in your own code after you receive the list. If the header is missing or invalid, treat the call as unauthenticated and check your credential handling rather than changing the endpoint path.

Request contract: method, path, and documented inputs

The request contract is minimal: method GET, path /v1/notifications/, and the x-access-key header. There is no documented request body and no documented query string. Keep the method and path exact, including the trailing slash, and use {{API_BASE_URL}} as the origin placeholder in samples so the same code can be pointed at a different environment later. The request example is titled List notification subscriptions request.

Response body field map for 200 application/json

A successful call returns 200 with an application/json body containing success as a required boolean and notifications as a required array of subscription objects. Each subscription object requires id as a string, channel as a string enum of webhook or email, profileId as string or null, eventTypes as an array of strings, onlyScheduledPosts as a boolean, enabled as a boolean, lastTestAt as a date-time string or null, lastTestStatus as a string or null, createdAt as a date-time string, and updatedAt as a date-time string. The webhook object is optional and, when present, requires url as a uri string and secret as a string. The email object is optional and, when present, requires recipients as an array of email strings with between 1 and 10 items. The full field map is in the table titled Response field map for 200 application/json.

Event types and channel decision criteria

Use channel to distinguish delivery method: webhook subscriptions carry a webhook object with url and secret, while email subscriptions carry an email object with recipients. Use enabled to distinguish active subscriptions from disabled ones, and use eventTypes to see which events a subscription covers. The documented event type values are post.scheduled, post.published, post.partial, post.failed, account.reauthorization_required, and account.disconnected. Use onlyScheduledPosts together with eventTypes when you need to find subscriptions scoped to scheduled posts, for example subscriptions where onlyScheduledPosts is true and eventTypes includes post.scheduled. Use profileId to group subscriptions by profile, remembering that profileId can be null. Use lastTestAt and lastTestStatus together to judge whether a subscription has been tested and what the last test reported; both can be null when no test has been recorded.

200 application/json worked example

The worked example titled 200 application/json response example shows the literal shape of a successful response, including a webhook subscription subscribed to post.scheduled with onlyScheduledPosts set to true. The example titled Parse the response and filter by eventTypes and onlyScheduledPosts shows how to read the notifications array in code and keep only subscriptions that are scoped to scheduled posts and include post.scheduled. When you parse a real response, first check success, then iterate notifications, and handle optional webhook and email objects by checking channel before reading their nested fields. Treat date-time fields such as createdAt, updatedAt, and lastTestAt as ISO 8601 strings and parse them with your language date parser rather than comparing them as plain strings.

Edge cases and nullable fields

An empty notifications array is a valid list result and means no subscriptions were returned; your code should render an empty state rather than assuming at least one item. A null profileId means the subscription is not tied to a specific profile value in the response, so do not group it under a profile identifier. Null lastTestAt and null lastTestStatus mean no test result is available, so do not display a test outcome for that subscription. A missing webhook object on an email subscription, or a missing email object on a webhook subscription, is expected because both objects are optional; read the object that matches channel. The edge case matrix is in the table titled Edge cases and nullable fields. No additional error codes are documented for this operation in the source, so do not invent status handling beyond the documented 200 response.

Immutable source contract sheet and origin-modular HTTP samples

Keep the immutable source contract sheet alongside this guide when implementing: GET /v1/notifications/, x-access-key header, and the 200 application/json schema with its exact field names, types, requiredness, enums, and constraints. Use the origin-modular samples with {{API_BASE_URL}} before the unchanged path so environment changes do not require rewriting the path. Related operations for creating and retrieving a single subscription are linked as proposed internal links and should be checked before adding write or single-item read behavior to your integration.

Response field map for 200 application/json
FieldTypeRequiredConstraints / notes
successbooleanYesTop-level response flag.
notificationsarray<object>YesList of subscription objects; may be empty.
notifications[].idstringYesSubscription identifier.
notifications[].channelstringYesEnum: "webhook" | "email".
notifications[].profileIdstring | nullYesNullable; null means no profile value in response.
notifications[].eventTypesarray<string>YesEnum values: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected".
notifications[].onlyScheduledPostsbooleanYesScopes subscription to scheduled posts.
notifications[].enabledbooleanYesWhether subscription is enabled.
notifications[].webhookobjectNoOptional; expected for webhook channel.
notifications[].webhook.urlstringYes when webhook presentFormat: uri.
notifications[].webhook.secretstringYes when webhook presentWebhook signing secret (masked in list responses).
notifications[].emailobjectNoOptional; expected for email channel.
notifications[].email.recipientsarray<string>Yes when email present1 <= items <= 10; items are email strings.
notifications[].lastTestAtstring | nullYesNullable; format: date-time.
notifications[].lastTestStatusstring | nullYesNullable; last subscription test result.
notifications[].createdAtstringYesFormat: date-time.
notifications[].updatedAtstringYesFormat: date-time.

Exact captured contract; origin modularized only in samples.

Edge cases and nullable fields
CaseWhat the response showsHow to handle it
Empty notifications arraynotifications is an empty arrayRender an empty state; do not assume at least one subscription.
profileId is nullprofileId: nullDo not group under a profile identifier.
lastTestAt is nulllastTestAt: nullNo test timestamp available; do not display a test time.
lastTestStatus is nulllastTestStatus: nullNo test result available; do not display a test outcome.
webhook object missingwebhook absent on an email subscriptionRead email.recipients instead; both objects are optional.
email object missingemail absent on a webhook subscriptionRead webhook.url and webhook.secret instead; both objects are optional.
Disabled subscriptionenabled: falseExclude from active-notification logic or surface as disabled.
Scheduled-post scopeonlyScheduledPosts: true with post.scheduled in eventTypesInclude when filtering for scheduled-post notifications.

No error codes invented; only documented 200 contract is described.

List notification subscriptions request
curl -X GET "{{API_BASE_URL}}/v1/notifications/" -H "x-access-key: <token>"
200 application/json response example
{
  "success": true,
  "notifications": [
    {
      "id": "string",
      "channel": "webhook",
      "profileId": "string",
      "eventTypes": [
        "post.scheduled"
      ],
      "onlyScheduledPosts": true,
      "enabled": true,
      "webhook": {
        "url": "http://example.com",
        "secret": "string"
      },
      "email": {
        "recipients": [
          "[email protected]"
        ]
      },
      "lastTestAt": "2019-08-24T14:15:22Z",
      "lastTestStatus": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.notificationsarray<object>__2Yes
response#1response.notifications[]object__3
response#1response.notifications[].idstring__4Yes
response#1response.notifications[].channelstring__5Yeskind: ; value: "webhook" | "email"
response#1response.notifications[].profileIdstring | null__6Yes
response#1response.notifications[].profileId[variant1]string__6_type:string
response#1response.notifications[].profileId[variant2]null__6_type:null
response#1response.notifications[].eventTypesarray<string>__7Yes
response#1response.notifications[].eventTypes[]string__8kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
response#1response.notifications[].onlyScheduledPostsboolean__9Yes
response#1response.notifications[].enabledboolean__10Yes
response#1response.notifications[].webhookobject__11No
response#1response.notifications[].webhook.urlstring__12Yeskind: ; value: uri
response#1response.notifications[].webhook.secretstring__13YesWebhook signing secret (masked in list responses)
response#1response.notifications[].emailobject__14No
response#1response.notifications[].email.recipientsarray<string>__15Yeskind: ; value: 1 <= items <= 10
response#1response.notifications[].email.recipients[]string__16kind: ; value: email
response#1response.notifications[].lastTestAtstring | null__17Yeskind: ; value: date-time
response#1response.notifications[].lastTestAt[variant1]string__17_type:stringkind: ; value: date-time
response#1response.notifications[].lastTestAt[variant2]null__17_type:nullkind: ; value: date-time
response#1response.notifications[].lastTestStatusstring | null__18Yes
response#1response.notifications[].lastTestStatus[variant1]string__18_type:string
response#1response.notifications[].lastTestStatus[variant2]null__18_type:null
response#1response.notifications[].createdAtstring__19Yeskind: ; value: date-time
response#1response.notifications[].updatedAtstring__20Yeskind: ; value: date-time