Full API and Integration Documentation

Subscribers

Subscribers are those that receive notifications via email, sms or webhook to incidents that are reported and subsequently updated.

Subscribers can be subscribed to:

  • a status page, where they get all updates to every incident automatically,
  • one or more components of a status page, where they get all updates to those components automatically, or
  • a specific incident, where they will only receive notifications for updates to that incident after they subscribed.

If a (page or component) subscriber fails to receive a notification, they will be quarantined. Quarantined subscribers are excluded from API responses and interactions by default.

Get a list of all subscribers
ENDPOINTS
  GET /pages/[page_id]/subscribers.json
  GET /pages/[page_id]/incidents/[incident_id]/subscribers.json

QUERY PARAMETERS
  type - One of "email", "sms", or "webhook". Controls the type of subscriber which will be returned.
  limit - Number indicating the maximum number of subscribers to return.
  page - 0-indexed page number for response paging: if `limit` is specified, the  response will not include the first `limit` * `page` subscribers.
  state - One of "active" (default, returns only subscribers who will receive notifications), "unconfirmed" (returns email subscribers who will not receive notifications because they have not yet confirmed their email), "quarantined" (returns quarantined subscribers who will not receive notifications because we have encountered an issue delivering to them), or "all" (return active, unconfirmed, and quarantined subscribers).
  sort_field - One of "primary" (default, sorts by the email address, SMS phone number or webhook endpoint URL), "created_at", "quarantined_at"
  sort_direction - One of "asc" (default, sorts ascending) or "desc" (sorts descending).

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074"

RESPONSE CODES
  200 - Successful call
  422 - Validation failed (see errors in response body)

SAMPLE RESPONSE
  [
    {
      "created_at": "2013-03-05T20:50:42Z",
      "id": "f6c6ggw8z0t1",
      "phone_country": "us",
      "phone_number": "9196022733"
    },
    {
      "created_at": "2013-03-05T20:50:42Z",
      "email": "steve@flyingkleinbrothers.com",
      "id": "xx5tcn6g80n8"
    },
    {
      "created_at": "2013-03-05T20:50:42Z",
      "email": "scott@flyingkleinbrothers.com",
      "id": "pm0tzg6pwkr4"
    }
  ]
Search for subscribers
ENDPOINTS
  GET /pages/[page_id]/subscribers.json?q=

QUERY PARAMETERS
  q - full text search string
  type - One of "email", "sms", or "webhook". Controls the type of subscriber which will be returned.
  limit - Number indicating the maximum number of subscribers to return.
  page - 0-indexed page number for response paging: if `limit` is specified, the  response will not include the first `limit` * `page` subscribers.
  state - One of "active" (default, returns only subscribers who will receive notifications), "unconfirmed" (returns email subscribers who will not receive notifications because they have not yet confirmed their email), "quarantined" (returns quarantined subscribers who will not receive notifications because we have encountered an issue delivering to them), or "all" (return active, unconfirmed, and quarantined subscribers).

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers.json?q=919 \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074"

RESPONSE CODES
  200 - Successful call
  422 - Validation failed (see errors in response body)

SAMPLE RESPONSE
  [
    {
      "created_at": "2013-03-05T20:50:42Z",
      "id": "f6c6ggw8z0t1",
      "phone_country": "us",
      "phone_number": "9196022733"
    }
  ]
Create a subscriber

You must be provide either subscriber[email], both of subscriber[phone_country] and subscriber[phone_number], or both of subscriber[email] and subscriber[endpoint].

A list of supported SMS countries can be found at https://api.statuspage.io/sms_countries.json

ENDPOINTS
  POST /pages/[page_id]/subscribers.json
  POST /pages/[page_id]/incidents/[incident_id]/subscribers.json

ATTRIBUTES
  subscriber[email] - The email address the subscriber wishes to receive notifications at (or, confirmation for webhook endpoint)
  subscriber[phone_number] - The phone number the subscriber wishes to receive notifications at
  subscriber[phone_country] - The two digit country code corresponding to the phone country
  subscriber[endpoint] - The URL endpoint you wish to wish to receive webhook notifications at (must be accompanied by email)
  subscriber[component_ids][] - Optional. Array of component ids that the created subscriber will be subscribed to. NOTE: you must have enabled component subscriptions to use this. This is not applicable to incident subscribers.
  subscriber[page_access_user] - Required if Access Control is enabled for the page. This is the code that identifies the PageAccessUser the subscription is for.

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X POST \
    -d "subscriber[email]=scott@scottkle.in" \
    -d "subscriber[component_ids][]=v8ghv9zlmr6r"

RESPONSE CODES
  201 - Successfully created
  422 - Validation failed (see errors in response body)

SAMPLE RESPONSE
  {
    "created_at": "2013-03-05T23:57:39Z",
    "email": "scott@scottkle.in",
    "id": "86z91fzjhlxy",
    "components": [ "v8ghv9zlmr6r" ]
  }
Delete a single subscriber
ENDPOINT
  DELETE /pages/[page_id]/subscribers/[subscriber_id].json
  DELETE /pages/[page_id]/incidents/[incident_id]/subscribers/[subscriber_id].json

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers/86z91fzjhlxy.json \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X DELETE

RESPONSE CODES
  200 - Successful call
  422 - Validation failed (see errors in response body)

SAMPLE RESPONSE
  {
    "created_at": "2013-03-05T23:57:39Z",
    "email": "scott@scottkle.in",
    "id": "86z91fzjhlxy"
  }
Resend email confirmation for a single, unconfirmed email subscriber
ENDPOINT
  POST /pages/[page_id]/subscribers/[subscriber_id]/resend_confirmation
  POST /pages/[page_id]/incidents/[incident_id]/subscribers/[subscriber_id]/resend_confirmation

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers/86z91fzjhlxy/resend_confirmation \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -X POST

RESPONSE CODES
  200 - Successful call
  422 - Validation failed (see errors in response body)
Delete a batch of subscribers
ENDPOINT
  POST /pages/[page_id]/subscribers/unsubscribe

BODY
  A JSON object structured as: {
    "subscribers": [array of subscriber ids to unsubscribe] or "all" to delete all matching subscribers,
    "type": one of "email", "sms", or "webhook" (optional - defaults to all subscriber types if not provided),
    "state": one of "active", "unconfirmed", "quarantined", or "all" (optional - defaults to "active")
  }

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers/unsubscribe \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -H 'Content-Type: application/json' \
    -d '{
      "subscribers": ["2sz5tthqgvcd", "q6ys2spbv4w2", "ftdzshb419h2"],
      "type": "webhook",
      "state": "active"
    }'

RESPONSE CODES
  204 - Successful call
  422 - Validation failed (see errors in response body)
Reactivate a batch of quarantined subscribers
ENDPOINT
  POST /pages/[page_id]/subscribers/reactivate

BODY
  A JSON object structured as: {
    "subscribers": [array of subscriber ids to reactivate] or "all" to reactivate all matching subscribers,
    "type": one of "email", "sms", or "webhook" (optional - defaults to all subscriber types if not provided)
  }

SAMPLE CALL
  curl https://api.statuspage.io/v1/pages/qfn30z5r6s5h/subscribers/reactivate \
    -H "Authorization: OAuth 2a7b9d4aac30956d537ac76850f4d78de30994703680056cc103862d53cf8074" \
    -H 'Content-Type: application/json' \
    -d '{
      "subscribers": ["2sz5tthqgvcd", "q6ys2spbv4w2", "ftdzshb419h2"],
      "type": "webhook"
    }'

RESPONSE CODES
  204 - Successful call
  422 - Validation failed (see errors in response body)