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.
| Field | Type | Required | Constraints / notes |
|---|---|---|---|
| success | boolean | Yes | Top-level response flag. |
| notifications | array<object> | Yes | List of subscription objects; may be empty. |
| notifications[].id | string | Yes | Subscription identifier. |
| notifications[].channel | string | Yes | Enum: "webhook" | "email". |
| notifications[].profileId | string | null | Yes | Nullable; null means no profile value in response. |
| notifications[].eventTypes | array<string> | Yes | Enum values: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected". |
| notifications[].onlyScheduledPosts | boolean | Yes | Scopes subscription to scheduled posts. |
| notifications[].enabled | boolean | Yes | Whether subscription is enabled. |
| notifications[].webhook | object | No | Optional; expected for webhook channel. |
| notifications[].webhook.url | string | Yes when webhook present | Format: uri. |
| notifications[].webhook.secret | string | Yes when webhook present | Webhook signing secret (masked in list responses). |
| notifications[].email | object | No | Optional; expected for email channel. |
| notifications[].email.recipients | array<string> | Yes when email present | 1 <= items <= 10; items are email strings. |
| notifications[].lastTestAt | string | null | Yes | Nullable; format: date-time. |
| notifications[].lastTestStatus | string | null | Yes | Nullable; last subscription test result. |
| notifications[].createdAt | string | Yes | Format: date-time. |
| notifications[].updatedAt | string | Yes | Format: date-time. |
Exact captured contract; origin modularized only in samples.
| Case | What the response shows | How to handle it |
|---|---|---|
| Empty notifications array | notifications is an empty array | Render an empty state; do not assume at least one subscription. |
| profileId is null | profileId: null | Do not group under a profile identifier. |
| lastTestAt is null | lastTestAt: null | No test timestamp available; do not display a test time. |
| lastTestStatus is null | lastTestStatus: null | No test result available; do not display a test outcome. |
| webhook object missing | webhook absent on an email subscription | Read email.recipients instead; both objects are optional. |
| email object missing | email absent on a webhook subscription | Read webhook.url and webhook.secret instead; both objects are optional. |
| Disabled subscription | enabled: false | Exclude from active-notification logic or surface as disabled. |
| Scheduled-post scope | onlyScheduledPosts: true with post.scheduled in eventTypes | Include when filtering for scheduled-post notifications. |
No error codes invented; only documented 200 contract is described.
curl -X GET "{{API_BASE_URL}}/v1/notifications/" -H "x-access-key: <token>"{
"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"
}
]
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| response#1 | response | object | __0 | |||
| response#1 | response.success | boolean | __1 | Yes | ||
| response#1 | response.notifications | array<object> | __2 | Yes | ||
| response#1 | response.notifications[] | object | __3 | |||
| response#1 | response.notifications[].id | string | __4 | Yes | ||
| response#1 | response.notifications[].channel | string | __5 | Yes | kind: ; value: "webhook" | "email" | |
| response#1 | response.notifications[].profileId | string | null | __6 | Yes | ||
| response#1 | response.notifications[].profileId[variant1] | string | __6_type:string | |||
| response#1 | response.notifications[].profileId[variant2] | null | __6_type:null | |||
| response#1 | response.notifications[].eventTypes | array<string> | __7 | Yes | ||
| response#1 | response.notifications[].eventTypes[] | string | __8 | kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" | ||
| response#1 | response.notifications[].onlyScheduledPosts | boolean | __9 | Yes | ||
| response#1 | response.notifications[].enabled | boolean | __10 | Yes | ||
| response#1 | response.notifications[].webhook | object | __11 | No | ||
| response#1 | response.notifications[].webhook.url | string | __12 | Yes | kind: ; value: uri | |
| response#1 | response.notifications[].webhook.secret | string | __13 | Yes | Webhook signing secret (masked in list responses) | |
| response#1 | response.notifications[].email | object | __14 | No | ||
| response#1 | response.notifications[].email.recipients | array<string> | __15 | Yes | kind: ; value: 1 <= items <= 10 | |
| response#1 | response.notifications[].email.recipients[] | string | __16 | kind: ; value: email | ||
| response#1 | response.notifications[].lastTestAt | string | null | __17 | Yes | kind: ; value: date-time | |
| response#1 | response.notifications[].lastTestAt[variant1] | string | __17_type:string | kind: ; value: date-time | ||
| response#1 | response.notifications[].lastTestAt[variant2] | null | __17_type:null | kind: ; value: date-time | ||
| response#1 | response.notifications[].lastTestStatus | string | null | __18 | Yes | ||
| response#1 | response.notifications[].lastTestStatus[variant1] | string | __18_type:string | |||
| response#1 | response.notifications[].lastTestStatus[variant2] | null | __18_type:null | |||
| response#1 | response.notifications[].createdAt | string | __19 | Yes | kind: ; value: date-time | |
| response#1 | response.notifications[].updatedAt | string | __20 | Yes | kind: ; value: date-time |