> For the complete documentation index, see [llms.txt](https://docs.statuspal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.statuspal.io/platform/api-reference/subscriptions.md).

# Subscriptions

Subscriptions endpoints

## GET /status\_pages/{subdomain}/subscriptions

> List subscriptions

```json
{"openapi":"3.0.1","info":{"title":"StatusPal API Reference","version":"2.0.0"},"tags":[{"name":"Subscriptions","description":"Subscriptions endpoints"}],"servers":[{"url":"https://statuspal.io/api/v2"},{"url":"https://statuspal.eu/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"StatusPageSubdomain":{"name":"subdomain","in":"path","description":"The subdomain of your status page.\n\nYou can find this under your status page settings, the Subdomain field is found under the \"Domain name\" section. Alternatively find it in the URL of your admin dashboard (e.g. statuspal.io/admin/`subdomain`).\n","required":true,"schema":{"type":"string"}}},"schemas":{"Subscription":{"required":["filter","service_ids","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of Subscription (`email`, `slack`, `sms`, `discord`)."},"filter":{"type":"string","description":"Filter the notifications to subscribe to (`all`, `services`, `incident`)."},"service_ids":{"type":"array","description":"An array of service IDs to subscribe to, required if filter is `services`.","items":{"type":"integer"}},"incident_types":{"type":"array","description":"An array of incident type keys. If set, the subscriber will be notified only about this type of incidents/maintenance.","items":{"type":"string"}},"incident_id":{"type":"integer","description":"An incident ID to subscribe to, required if filter is `incident`."},"email":{"type":"string","description":"The email to send the notifications to, required if type is `email`."},"confirm":{"type":"boolean","description":"Set to false to skip sending confirmation email for email subscriptions."},"country_dial_code":{"type":"string","description":"The country code of the phone number to send the notifications to, required if type is `sms`."},"phone_number":{"type":"string","description":"The phone number to send the notifications to, required if type is `sms`."},"webhook_url":{"type":"string","description":"The Discord webhook URL, required if type is `discord`."},"locale":{"type":"string","description":"The subscriber's locale."},"inserted_at":{"type":"string","description":"Datetime at which the record was inserted","format":"date-time","readOnly":true},"updated_at":{"type":"string","description":"Datetime at which the record was last updated","format":"date-time","readOnly":true},"metadata":{"type":"object","description":"Additional metadata associated with the subscription."},"subscription_group_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of the subscription groups this subscription belongs to. On update, the provided list replaces the previous one (not additive). Send `[]` to remove from all groups.\n"}}},"UnauthorizedError":{"type":"object","properties":{"error":{"type":"integer","description":"Unauthorized"}}},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Forbidden"}}},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","description":"Resource not found!"}}},"ServerError":{"type":"object","properties":{"error":{"type":"string","description":"Internal server error :("}}}},"responses":{"UnauthorizedError":{"description":"Authorization information is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenError":{"description":"You lack the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundError":{"description":"A resource with the provided ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"ServerError":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/status_pages/{subdomain}/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List subscriptions","operationId":"getSubscriptions","parameters":[{"$ref":"#/components/parameters/StatusPageSubdomain"},{"name":"filter","in":"query","description":"Filters by email address or phone number.\n\nIn order to search by phone number, the following is supported:\n\n1. Full phone number. Ensure the country code is prefixed by a + sign and\n  include a space between the country code and phone number (e.g. `+49 000000000` or `+49 000 000 000`)\n2. Country code (e.g. `+49`)\n3. Phone number without country code  (e.g. `000000000`)\n","schema":{"type":"string"}},{"name":"before","in":"query","description":"Used as a cursor for pagination.","schema":{"type":"string"}},{"name":"after","in":"query","description":"Used as a cursor for pagination.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Set the number of subscriptions to return in the response.\nThis defaults to 20 items, and can be a maximum of 100.\n","schema":{"type":"integer"}}],"responses":{"200":{"description":"The list of subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"links":{"type":"object","properties":{"next":{"type":"string","description":"Link for the next page."},"prev":{"type":"string","description":"Link for the previous page."}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer","description":"Shows the total amount of subscriptions."}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## POST /status\_pages/{subdomain}/subscriptions

> Adds a new subscription email, SMS or discord subscription

```json
{"openapi":"3.0.1","info":{"title":"StatusPal API Reference","version":"2.0.0"},"tags":[{"name":"Subscriptions","description":"Subscriptions endpoints"}],"servers":[{"url":"https://statuspal.io/api/v2"},{"url":"https://statuspal.eu/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"StatusPageSubdomain":{"name":"subdomain","in":"path","description":"The subdomain of your status page.\n\nYou can find this under your status page settings, the Subdomain field is found under the \"Domain name\" section. Alternatively find it in the URL of your admin dashboard (e.g. statuspal.io/admin/`subdomain`).\n","required":true,"schema":{"type":"string"}}},"schemas":{"SubscriptionObj":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}},"Subscription":{"required":["filter","service_ids","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of Subscription (`email`, `slack`, `sms`, `discord`)."},"filter":{"type":"string","description":"Filter the notifications to subscribe to (`all`, `services`, `incident`)."},"service_ids":{"type":"array","description":"An array of service IDs to subscribe to, required if filter is `services`.","items":{"type":"integer"}},"incident_types":{"type":"array","description":"An array of incident type keys. If set, the subscriber will be notified only about this type of incidents/maintenance.","items":{"type":"string"}},"incident_id":{"type":"integer","description":"An incident ID to subscribe to, required if filter is `incident`."},"email":{"type":"string","description":"The email to send the notifications to, required if type is `email`."},"confirm":{"type":"boolean","description":"Set to false to skip sending confirmation email for email subscriptions."},"country_dial_code":{"type":"string","description":"The country code of the phone number to send the notifications to, required if type is `sms`."},"phone_number":{"type":"string","description":"The phone number to send the notifications to, required if type is `sms`."},"webhook_url":{"type":"string","description":"The Discord webhook URL, required if type is `discord`."},"locale":{"type":"string","description":"The subscriber's locale."},"inserted_at":{"type":"string","description":"Datetime at which the record was inserted","format":"date-time","readOnly":true},"updated_at":{"type":"string","description":"Datetime at which the record was last updated","format":"date-time","readOnly":true},"metadata":{"type":"object","description":"Additional metadata associated with the subscription."},"subscription_group_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of the subscription groups this subscription belongs to. On update, the provided list replaces the previous one (not additive). Send `[]` to remove from all groups.\n"}}},"BadRequestError":{"type":"object","properties":{"error":{"type":"string","description":"Bad request!"}}},"UnauthorizedError":{"type":"object","properties":{"error":{"type":"integer","description":"Unauthorized"}}},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Forbidden"}}},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","description":"Resource not found!"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","description":"A dictionary where each key contains the name of a field with a validation error and the value an array with the validation errors"}}},"ServerError":{"type":"object","properties":{"error":{"type":"string","description":"Internal server error :("}}}},"responses":{"BadRequestError":{"description":"Bad request error. Probably JSON syntax is wrong, check with jsonlint.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestError"}}}},"UnauthorizedError":{"description":"Authorization information is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenError":{"description":"You lack the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundError":{"description":"A resource with the provided ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"ValidationError":{"description":"There was a validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"ServerError":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/status_pages/{subdomain}/subscriptions":{"post":{"tags":["Subscriptions"],"summary":"Adds a new subscription email, SMS or discord subscription","operationId":"addSubscription","parameters":[{"$ref":"#/components/parameters/StatusPageSubdomain"}],"requestBody":{"description":"The subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionObj"}}},"required":true},"responses":{"200":{"description":"The subscription was created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionObj"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## GET /status\_pages/{subdomain}/subscriptions/{subscriptionId}

> Get a subscription

```json
{"openapi":"3.0.1","info":{"title":"StatusPal API Reference","version":"2.0.0"},"tags":[{"name":"Subscriptions","description":"Subscriptions endpoints"}],"servers":[{"url":"https://statuspal.io/api/v2"},{"url":"https://statuspal.eu/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"StatusPageSubdomain":{"name":"subdomain","in":"path","description":"The subdomain of your status page.\n\nYou can find this under your status page settings, the Subdomain field is found under the \"Domain name\" section. Alternatively find it in the URL of your admin dashboard (e.g. statuspal.io/admin/`subdomain`).\n","required":true,"schema":{"type":"string"}},"SubscriptionId":{"name":"subscriptionId","in":"path","description":"The ID of a subscription","required":true,"schema":{"type":"string"}}},"schemas":{"SubscriptionObj":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}},"Subscription":{"required":["filter","service_ids","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of Subscription (`email`, `slack`, `sms`, `discord`)."},"filter":{"type":"string","description":"Filter the notifications to subscribe to (`all`, `services`, `incident`)."},"service_ids":{"type":"array","description":"An array of service IDs to subscribe to, required if filter is `services`.","items":{"type":"integer"}},"incident_types":{"type":"array","description":"An array of incident type keys. If set, the subscriber will be notified only about this type of incidents/maintenance.","items":{"type":"string"}},"incident_id":{"type":"integer","description":"An incident ID to subscribe to, required if filter is `incident`."},"email":{"type":"string","description":"The email to send the notifications to, required if type is `email`."},"confirm":{"type":"boolean","description":"Set to false to skip sending confirmation email for email subscriptions."},"country_dial_code":{"type":"string","description":"The country code of the phone number to send the notifications to, required if type is `sms`."},"phone_number":{"type":"string","description":"The phone number to send the notifications to, required if type is `sms`."},"webhook_url":{"type":"string","description":"The Discord webhook URL, required if type is `discord`."},"locale":{"type":"string","description":"The subscriber's locale."},"inserted_at":{"type":"string","description":"Datetime at which the record was inserted","format":"date-time","readOnly":true},"updated_at":{"type":"string","description":"Datetime at which the record was last updated","format":"date-time","readOnly":true},"metadata":{"type":"object","description":"Additional metadata associated with the subscription."},"subscription_group_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of the subscription groups this subscription belongs to. On update, the provided list replaces the previous one (not additive). Send `[]` to remove from all groups.\n"}}},"UnauthorizedError":{"type":"object","properties":{"error":{"type":"integer","description":"Unauthorized"}}},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Forbidden"}}},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","description":"Resource not found!"}}},"ServerError":{"type":"object","properties":{"error":{"type":"string","description":"Internal server error :("}}}},"responses":{"UnauthorizedError":{"description":"Authorization information is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenError":{"description":"You lack the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundError":{"description":"A resource with the provided ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"ServerError":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/status_pages/{subdomain}/subscriptions/{subscriptionId}":{"get":{"tags":["Subscriptions"],"summary":"Get a subscription","operationId":"getSubscription","parameters":[{"$ref":"#/components/parameters/StatusPageSubdomain"},{"$ref":"#/components/parameters/SubscriptionId"}],"responses":{"200":{"description":"The subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionObj"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## PUT /status\_pages/{subdomain}/subscriptions/{subscriptionId}

> Update the subscription

```json
{"openapi":"3.0.1","info":{"title":"StatusPal API Reference","version":"2.0.0"},"tags":[{"name":"Subscriptions","description":"Subscriptions endpoints"}],"servers":[{"url":"https://statuspal.io/api/v2"},{"url":"https://statuspal.eu/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"StatusPageSubdomain":{"name":"subdomain","in":"path","description":"The subdomain of your status page.\n\nYou can find this under your status page settings, the Subdomain field is found under the \"Domain name\" section. Alternatively find it in the URL of your admin dashboard (e.g. statuspal.io/admin/`subdomain`).\n","required":true,"schema":{"type":"string"}},"SubscriptionId":{"name":"subscriptionId","in":"path","description":"The ID of a subscription","required":true,"schema":{"type":"string"}}},"schemas":{"SubscriptionObj":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}}},"Subscription":{"required":["filter","service_ids","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of Subscription (`email`, `slack`, `sms`, `discord`)."},"filter":{"type":"string","description":"Filter the notifications to subscribe to (`all`, `services`, `incident`)."},"service_ids":{"type":"array","description":"An array of service IDs to subscribe to, required if filter is `services`.","items":{"type":"integer"}},"incident_types":{"type":"array","description":"An array of incident type keys. If set, the subscriber will be notified only about this type of incidents/maintenance.","items":{"type":"string"}},"incident_id":{"type":"integer","description":"An incident ID to subscribe to, required if filter is `incident`."},"email":{"type":"string","description":"The email to send the notifications to, required if type is `email`."},"confirm":{"type":"boolean","description":"Set to false to skip sending confirmation email for email subscriptions."},"country_dial_code":{"type":"string","description":"The country code of the phone number to send the notifications to, required if type is `sms`."},"phone_number":{"type":"string","description":"The phone number to send the notifications to, required if type is `sms`."},"webhook_url":{"type":"string","description":"The Discord webhook URL, required if type is `discord`."},"locale":{"type":"string","description":"The subscriber's locale."},"inserted_at":{"type":"string","description":"Datetime at which the record was inserted","format":"date-time","readOnly":true},"updated_at":{"type":"string","description":"Datetime at which the record was last updated","format":"date-time","readOnly":true},"metadata":{"type":"object","description":"Additional metadata associated with the subscription."},"subscription_group_ids":{"type":"array","items":{"type":"integer"},"description":"IDs of the subscription groups this subscription belongs to. On update, the provided list replaces the previous one (not additive). Send `[]` to remove from all groups.\n"}}},"BadRequestError":{"type":"object","properties":{"error":{"type":"string","description":"Bad request!"}}},"UnauthorizedError":{"type":"object","properties":{"error":{"type":"integer","description":"Unauthorized"}}},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Forbidden"}}},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","description":"Resource not found!"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","description":"A dictionary where each key contains the name of a field with a validation error and the value an array with the validation errors"}}},"ServerError":{"type":"object","properties":{"error":{"type":"string","description":"Internal server error :("}}}},"responses":{"BadRequestError":{"description":"Bad request error. Probably JSON syntax is wrong, check with jsonlint.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestError"}}}},"UnauthorizedError":{"description":"Authorization information is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenError":{"description":"You lack the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundError":{"description":"A resource with the provided ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"ValidationError":{"description":"There was a validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"ServerError":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}}},"paths":{"/status_pages/{subdomain}/subscriptions/{subscriptionId}":{"put":{"tags":["Subscriptions"],"summary":"Update the subscription","operationId":"updateSubscription","parameters":[{"$ref":"#/components/parameters/StatusPageSubdomain"},{"$ref":"#/components/parameters/SubscriptionId"}],"requestBody":{"description":"The subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionObj"}}},"required":true},"responses":{"200":{"description":"The subscription was updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionObj"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## DELETE /status\_pages/{subdomain}/subscriptions/{subscriptionId}

> Deletes the subscription

```json
{"openapi":"3.0.1","info":{"title":"StatusPal API Reference","version":"2.0.0"},"tags":[{"name":"Subscriptions","description":"Subscriptions endpoints"}],"servers":[{"url":"https://statuspal.io/api/v2"},{"url":"https://statuspal.eu/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"}},"parameters":{"StatusPageSubdomain":{"name":"subdomain","in":"path","description":"The subdomain of your status page.\n\nYou can find this under your status page settings, the Subdomain field is found under the \"Domain name\" section. Alternatively find it in the URL of your admin dashboard (e.g. statuspal.io/admin/`subdomain`).\n","required":true,"schema":{"type":"string"}},"SubscriptionId":{"name":"subscriptionId","in":"path","description":"The ID of a subscription","required":true,"schema":{"type":"string"}}},"responses":{"UnauthorizedError":{"description":"Authorization information is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}},"ForbiddenError":{"description":"You lack the necessary permissions to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"NotFoundError":{"description":"A resource with the provided ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"ServerError":{"description":"Unexpected error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}},"schemas":{"UnauthorizedError":{"type":"object","properties":{"error":{"type":"integer","description":"Unauthorized"}}},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Forbidden"}}},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","description":"Resource not found!"}}},"ServerError":{"type":"object","properties":{"error":{"type":"string","description":"Internal server error :("}}}}},"paths":{"/status_pages/{subdomain}/subscriptions/{subscriptionId}":{"delete":{"tags":["Subscriptions"],"summary":"Deletes the subscription","operationId":"deleteSubscription","parameters":[{"$ref":"#/components/parameters/StatusPageSubdomain"},{"$ref":"#/components/parameters/SubscriptionId"}],"responses":{"204":{"description":"Subscription deleted successfully","content":{}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```