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": "[email protected]",
"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 = '[email protected]' # 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')