Get Alert Recipients

Last modified on August 24, 2020

Get all existing alert recipients, optionally filtered by type or alerting method.

Request URL

GET https://api.alertsite.com/api/v3/recipients[?parameters]

Authentication

The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

Query parameters

Query parameters are optional, but can be used to filter the returned data.

type

Filter the recipients by alert types:

  • Availability - returns recipients with availability alerts enabled (availability_alert = true).

  • Performance - returns recipients with performance alerts enabled (performance_alert = true).

If omitted, all recipients are returned.

method_id

Filter the recipients by alerting method:

  • 1 – E-mail (text format)

  • 2 – Alphanumeric (text) pager

  • 3 – Numeric pager (pause after dial method)

  • 4 – E-mail to wireless device (cell phone, pager, Blackberry, etc.)

  • 5 – Numeric pager (wait for quiet method)

  • 6 – SMS message

  • 8 – SNMP trap (snmpv1)

  • 9 – SNMP trap (snmpv2c)

  • 10 – POST request to web server

  • 11 – Telephone message (voip)

  • 12 – E-mail (HTML format)

  • 14 – PagerDuty

  • 15 – Splunk

  • 16 – POST JSON request to web server (also known as “JSON alerts”)

  • 17 – ServiceNow

If omitted, all recipients are returned.

limit

Integer. The maximum number of results to return. Use together with offset to paginate through a large number of results.

offset

Integer. Return the results starting from this offset (0-based).

Response body

On success, the operation returns HTTP status 200 and a JSON object containing metadata and results, where results is an array of Recipient objects.

{
  "metadata": {
    "__permissions": {
      "acl": 7
    },
    "resultset": {
      "count": 1,
      "limit": null,
      "offset": "0"
    }
  },
  "results": [
    {
      "attach_screen_capture": true,
      "attach_server_response": true,
      "availability_alert": true,
      "blackout_ids": [
        "1234"
      ],
      "id": 90626,
      "method_description": "E-mail (HTML format)",
      "method_id": 12,
      "name": "DevOps mailing list",
      "notifier_groups": [
        "9916"
      ],
      "notify_on_clear": true,
      "password": null,
      "performance_alert": true,
      "performance_alert_type": "20",
      "recipient": "devops@example.com",
      "remote_commands": false,
      "repeat_performance_alerts": true,
      "start_threshold": 1,
      "stop_threshold": 10,
      "username": null
    },
  ]
}

If no recipients matching the specified criteria are found, an empty results array is returned:

{
  "metadata": {
    "__permissions": {
      "acl": 7
    },
    "resultset": {
      "count": 0,
      "limit": null,
      "offset": "0"
    }
  },
  "results": []
}

Error responses have HTTP status codes in the 4xx range.

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

cURL

Get all recipients:

curl https://api.alertsite.com/api/v3/recipients -H "Authorization: Bearer ACCESS_TOKEN"

Get all recipients who receive performance alerts:

curl https://api.alertsite.com/api/v3/recipients?type=Performance -H "Authorization: Bearer ACCESS_TOKEN"

Get all SMS recipients:

curl https://api.alertsite.com/api/v3/recipients?method_id=6 -H "Authorization: Bearer ACCESS_TOKEN"

Python

This example prints a list of all recipients.

Python

# Python 3.5+
import requests  # Requests library http://docs.python-requests.org
import json

baseUrl = 'https://api.alertsite.com/api/v3'
username = 'demo@example.com'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

# Log in
payload = {'username': username, 'password': password}
r = requests.post(baseUrl + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']

# Get all recipients
r = requests.get(baseUrl + '/recipients', headers={'Authorization': 'Bearer ' + token})
result = r.json()

if r.status_code == requests.codes.ok:
    recipients = result['results']
    print('Total recipients found:', len(recipients), '\n')

    for recipient in recipients:
        print('Recipient: {recipient}\n'
              'Availability alerts enabled? {availability_alert}\n'
              'Performance alerts enabled? {performance_alert}\n'.format(**recipient))
else:
    print('Could not get recipients. The following error(s) occurred:', *result['errors'], sep='\n')

See Also

Alert Recipient Operations

Highlight search results