Welcome to the Pingdom API!
The Pingdom API is a way for you to automate your interaction with the Pingdom system. With the API, you can create your own scripts or applications with most of the functionality you can find inside the Pingdom control panel.
The Pingdom API is RESTful and HTTP-based. Basically, this means that the communication is made through normal HTTP requests.
Authentication
Authentication is needed in order to use the Pingdom API, and for this a Pingdom account is required. The credentials used for accessing the API are the same used to access the Pingdom control panel - in other words your email address and your password. You will also need an application key.
The authentication method for user credentials is HTTP Basic Access Authentication (encrypted over HTTPS). This means you will provide your credentials every time you make a request. No sessions are used.
For further information on HTTP Basic Access Authentication, take a look at: http://en.wikipedia.org/wiki/HTTP_authentication
You generate your application key inside the Pingdom control panel. It is supposed to be unique on an application basis, not user basis. This means that if you produce an application and then distribute it to the public, all users of this application should use the same application key.
The application key is provided as a normal HTTP header in your request. Here is an example:
App-Key: zoent8w9cbt810rsdkweir23vcxb87zrt5541
Multi-User Authentication
Feature only available for Team accounts. If you have multiple users connected to your account you can supply a HTTP header Account‑Email with the email address of the account from which you want to get information.
Example: Your account is foo@example.com. The account on which you want to perform the API request is bar@example.com. You would authenticate as foo@example.com, with the Account‑Email header set to bar@example.com.
Request
> GET /checks HTTP/1.1 > Host: api.pingdom.com > Authentication: Zm9vQGV4YW1wbGUuY29tOnBhc3N3b3Jk > App-Key: 1234567890abcdef1234567890abcdef > Account-Email: bar@example.com
Response
< HTTP/1.1 200 OK < Content-Length: 13 < Content-Type: application/json {"checks":[]}
Server Address
The base server address is: https://api.pingdom.com
Please note that HTTPS is required. You will not be able to connect through unencrypted HTTP.
Providing Parameters
GET requests should provide their parameters as a query string, part of the URL.
POST, PUT and DELETE requests should provide their parameters as a query string. This should be part of the body, URL or a combination.
The encoding of the query string should be standard URL-encoding, as provided by various programming libraries.
HTTP/1.1 Status Code Definitions
The HTTP status code returned by a successful API request is defined in the documentation for that method. Usually, this will be 200 OK.
If something goes wrong, other codes may be returned. The API uses standard HTTP/1.1 status codes defined by RFC 2616.
JSON Responses
All responses are sent JSON-encoded. The specific responses (successful ones) are described in the documentation section for each method.
However, if something goes wrong, our standard JSON error message (together with an appropriate status code) follows this format:
{ "error":{ "statuscode":403, "statusdesc":"Forbidden", "errormessage":"Something went wrong! This string describes what happened." } }
See http://en.wikipedia.org/wiki/Json for more information on JSON.
Please note that all attributes of a method response are not always present. A client application should never assume that a certain attribute is present in a response.
Limits
The Pingdom API has usage limits to avoid individual rampant applications degrading the overall user experience. There are two layers of limits, the first cover a shorter period of time and the second a longer period. This enables you to "burst" requests for shorter periods. There are two HTTP headers in every response describing your limits status.
The response headers are:
- Req-Limit-Short
- Req-Limit-Long
An example of the values of these headers:
- Req-Limit-Short: Remaining: 394 Time until reset: 3589
- Req-Limit-Long: Remaining: 71994 Time until reset: 2591989
In this case, we can see that the user has 394 requests left until the short limit is reached. In 3589 seconds, the short limit will be reset. In similar fashion, the long limit has 71994 requests left, and will be reset in 2591989 seconds.
If you feel restricted by these limits, please feel free to contact Pingdom support and request a higher limit. The limits are primarily here to protect the system from poorly coded applications, not to restrict you as a user.
gzip
Responses can be gzip-encoded on demand. This is nice if your bandwidth is limited, or if big results are causing performance issues.
To enable gzip, simply add the following header to your request:
Accept-Encoding: gzip
Best Practices
Use caching
If you are building a web page using the Pingdom API, we recommend that you do all API request on the server side, and if possible cache them. If you get any substantial traffic, you do not want to call the API each time you get a page hit, since this may cause you to hit the request limit faster than expected. In general, whenever you can cache data, do so.
Send your user credentials in a preemptive manner
Some HTTP clients omit the authentication header, and make a second request with the header when they get a 401 Unauthorized response. Please make sure you send the credentials directly, to avoid unnecessary requests.
Use common sense
Should be simple enough. For example, don't check for the status of a check every other second. The highest check resolution is one minute. Checking more often than that won't give you much of an advantage.
The Internet is unreliable
Networks in general are unreliable, and particularly one as large and complex as the Internet. Your application should not assume it will get an answer. There may be timeouts.
PHP Code Example
"This is too much to read. I just want to get started right now! Give me a simple example!"
Here is a short example of how you can use the API with PHP. You need the cURL extension for PHP.
The example prints the current status of all your checks. This sample obviously focuses on Pingdom API code and does not worry about any potential problems connecting to the API, but your code should.
Code
<?php
// Init cURL
$curl = curl_init();
// Set target URL
curl_setopt($curl, CURLOPT_URL, "https://api.pingdom.com/api/2.0/checks");
// Set the desired HTTP method (GET is default, see the documentation for each request)
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
// Set user (email) and password
curl_setopt($curl, CURLOPT_USERPWD, "johndoe@example.com:password");
// Add a http header containing the application key (see the Authentication section of this document)
curl_setopt($curl, CURLOPT_HTTPHEADER, array("App-Key: zoent8w9cbt810rsdkweir23vcxb87zrt5541"));
// Ask cURL to return the result as a string
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// Execute the request and decode the json result into an associative array
$response = json_decode(curl_exec($curl),true);
// Check for errors returned by the API
if (isset($response['error'])) {
print "Error: " . $response['error']['errormessage'] . "\n";
exit;
}
// Fetch the list of checks from the response
$checksList = $response['checks'];
// Print the names and statuses of all checks in the list
foreach ($checksList as $check) {
print $check['name'] . " is " . $check['status'] . "\n";
}
?>
Example output:
Ubuntu Packages is up Google is up Pingdom is up My server 1 is down My server 2 is up
If you are running PHP on Windows, you need to be sure that you have installed the CA certificates for HTTPS/SSL to work correctly. Please see the cURL manual for more information. As a quick (but unsafe) workaround, you can add the following cURL option to ignore certificate validation.
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, 0);
Rest Requests
Below you can find descriptions and examples for all methods.
Resource: Actions
Method: Get Actions (Alerts) List
Description
Returns a list of actions (alerts) that have been generated for your account.
URL Syntax
/api/2.1/actions
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Only include actions generated later than this timestamp. Format is UNIX time. | Integer | no | |
to | Only include actions generated prior to this timestamp. Format is UNIX time. | Integer | no | |
limit | Limits the number of returned results to the specified quantity. | Integer (max 300) | no | 100 |
offset | Offset for listing. | Integer | no | 0 |
checkids | Comma-separated list of check identifiers. Limit results to actions generated from these checks. | String | no | |
userids | Comma-separated list of user identifiers. Limit results to actions sent to these users. | String | no | All users |
status | Comma-separated list of statuses. Limit results to actions with these statuses. | String (pending, sent, delivered, error, not_delivered, no_credits) | no | All statuses |
via | Comma-separated list of via mediums. Limit results to actions with these mediums. | String (email, sms, twitter, iphone, android) | no | All mediums |
Response Attributes
Attribute | Description | Type |
---|---|---|
actions.alerts.(entry) | Alert entry | Object |
actions.alerts.(entry).username | Name of alerted user | String |
actions.alerts.(entry).userid | Identifier of alerted user | String |
actions.alerts.(entry).checkid | Identifier of check | String |
actions.alerts.(entry).time | Time of alert generation. Format UNIX time | Integer |
actions.alerts.(entry).via | Alert medium | String (email, sms, twitter, iphone, android) |
actions.alerts.(entry).status | Alert status | String (sent, delivered, error, notdelivered, nocredits) |
actions.alerts.(entry).messageshort | Short description of message | String |
actions.alerts.(entry).messagefull | Full message body | String |
actions.alerts.(entry).sentto | Target address, phone number etc | String |
actions.alerts.(entry).charged | True if your account was charged for this message | Boolean |
Examples
Get a list of the latest alerts.
Request
GET /api/2.1/actions?limit=2
Response
{ "actions": { "alerts": [ { "username" : "John Doe", "userid" : 111250, "checkid" : 241688, "time" : 1292248276, "via" : "sms", "status" : "delivered", "messageshort" : "up", "messagefull" : "PingdomAlert UP: MyCheck (example.com) is UP again at 2010-12-13 14:50:54. Downtime: 12m.", "sentto" : "46-555555", "charged" : true }, { "username" : "John Doe", "userid" : 111250, "checkid" : 241688, "time" : 1292248254, "via" : "email", "status" : "sent", "messageshort" : "up", "messagefull" : "FROM:alert@pingdom.com\r\nTO:john@example.com\r\nSubject:UP alert: MyCheck (example.com) is UP\r\n\r\nPingdomAlert UP:\r\nMyCheck (example.com) is UP again at 2010-12-13 14:50:54, after 12m of downtime.", "sentto" : "john@example.com", "charged" : false } ] } }
Resource: Analysis
Method: Get Root Cause Analysis Results List
Description
Returns a list of the latest root cause analysis results for a specified check.
URL Syntax
/api/2.1/analysis/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
limit | Limits the number of returned results to the specified quantity. | Integer | no | 100 |
offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
from | Return only results with timestamp of first test greater or equal to this value. Format is UNIX timestamp. | Integer | no | 0 |
to | Return only results with timestamp of first test less or equal to this value. Format is UNIX timestamp. | Integer | no | Current timestamp |
Response Attributes
Attribute | Description | Type |
---|---|---|
analysis.(entry).id | Analysis id | Integer |
analysis.(entry).timefirsttest | Time of test that initiated the confirmation test | Integer |
analysis.(entry).timeconfirmtest | Time of the confirmation test that performed the error analysis | Integer |
Examples
Get a list of the latest analyses for check 161748
Request
GET /api/2.1/analysis/161748
Response
{ "analysis" : [ { "id" : 28739021, "timefirsttest" : 1290441826, "timeconfirmtest" : 1290441865 }, { "id" : 28737907, "timefirsttest" : 1290440924, "timeconfirmtest" : 1290440932 }, { "id" : 28589686, "timefirsttest" : 1290263024, "timeconfirmtest" : 1290263059 }, { "id" : 28063742, "timefirsttest" : 1289647724, "timeconfirmtest" : 1289647760 } ] }
Method: Get Raw Analysis Results
Description
Returns the raw result for a specified error analysis. This data is primarily intended for internal use, but you might be interested in it as well. However, there is no real documentation for this data at the moment. In the future, we may add a new API method that provides a more user-friendly format.
URL Syntax
/api/2.1/analysis/{checkid}/{analysisid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|
Examples
Resource: Checks
Method: Get Check List
Description
Returns a list overview of all checks.
URL Syntax
/api/2.1/checks
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
limit | Limits the number of returned probes to the specified quantity. (Max value is 25000) | Integer | no | 25000 |
offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
showencryption | If set, show encryption setting for each check | Boolean | no | false |
include_tags | Include tag list for each check. Tags can be marked as "a" or "u", for auto tagged or user tagged. | Boolean | no | false |
include_severity | Include severity level for each check. | Boolean | no | false |
tags | Tag list separated by commas. As an example "nginx,apache" would filter out all responses except those tagged nginx or apache. | String | no | N/A |
Response Attributes
Attribute | Description | Type |
---|---|---|
checks.(entry).id | Check identifier | Integer |
checks.(entry).name | Check name | String |
checks.(entry).type | Check type | String |
checks.(entry).lasterrortime | Timestamp of last error (if any). Format is UNIX timestamp | Integer |
checks.(entry).lasttesttime | Timestamp of last test (if any). Format is UNIX timestamp | Integer |
checks.(entry).lastresponsetime | Response time (in milliseconds) of last test. | Integer |
checks.(entry).status | Current status of check | String (up, down, unconfirmed_down, unknown, paused) |
checks.(entry).resolution | How often should the check be tested? (minutes) | Integer |
checks.(entry).hostname | Target host | String |
checks.(entry).created | Creating time. Format is UNIX timestamp | Integer |
checks.(entry).tags | List of tags for check | Array |
checks.(entry).probe_filters | Filters used for probe selections | Array |
checks.(entry).ipv6 | Use ipv6 instead of ipv4 | Boolean |
counts.total | Total number of checks | Integer |
counts.filtered | Number of checks after tags filter was applied | Integer |
counts.limited | Number of checks after limit was applied | Integer |
Examples
Get all checks
Request
GET /api/2.1/checks&include_tags=true&tags=nginx,apache,ssh&limit=3
Response
{ "checks": [ { "hostname": "example.com", "id": 85975, "created": 1297181273, "lasterrortime": 1297446423, "lastresponsetime": 355, "lasttesttime": 1300977363, "name": "My check 1", "resolution": 1, "status": "up", "type": "http", "tags": [ { "name": "apache", "type": "a", "count": 2 } ] }, { "hostname": "mydomain.com", "id": 161748, "created": 1297181255, "lasterrortime": 1299194968, "lastresponsetime": 1141, "lasttesttime": 1300977268, "name": "My check 2", "resolution": 5, "status": "up", "type": "ping", "tags": [ { "name": "nginx", "type": "u", "count": 1 } ] }, { "hostname": "example.net", "id": 208655, "created": 1297181243, "lasterrortime": 1300527997, "lastresponsetime": 800, "lasttesttime": 1300977337, "name": "My check 3", "resolution": 1, "status": "down", "type": "http", "tags": [ { "name": "apache", "type": "a", "count": 2 } ] } ], "counts": { "total": 55, "limited": 3, "filtered": 5 } }
Method: Get Detailed Check Information
Description
Returns a detailed description of a specified check.
URL Syntax
/api/2.1/checks/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
include_teams | Include team connections for check. | Boolean | no | false |
Response Attributes
General attributes
Attribute | Description | Type |
---|---|---|
check.id | Check identifier | Integer |
check.name | Check name | String |
check.hostname | Target host | String |
check.status | Current check status | String (up, down, unconfirmed_down, unknown, paused) |
check.resolution | How often should the check be tested? (minutes) | Integer |
check.type | Contains one element representing the type of check and type-specific settings | Object |
check.userids.(entry) | Identifier of users who should receive alerts | Integer |
check.sendnotificationwhendown | Send notification when down n times | Integer |
check.notifyagainevery | Notify again every n result | Integer |
check.notifywhenbackup | Notify when back up again | Boolean |
check.lasterrortime | Timestamp of last error (if any). Format is UNIX timestamp | Integer |
check.lasttesttime | Timestamp of last test (if any). Format is UNIX timestamp | Integer |
check.lastresponsetime | Response time (in milliseconds) of last test. | Integer |
check.created | Creating time. Format is UNIX timestamp | Integer |
check.ipv6 | Use ipv6 instead of ipv4 | Boolean |
check.responsetime_threshold | Triggers a down alert if the response time exceeds threshold specified in ms | Integer |
check.integrationids.(entry) | Identifier of integration which should receive alerts | Integer |
check.teams.(entry).id | Identifier of team which should receive alerts | Integer |
check.teams.(entry).name | Name of team which should receive alerts | String |
HTTP attributes
Attribute | Description | Type |
---|---|---|
check.type.http.url | Path to target on server | String |
check.type.http.encryption | Connection encryption | Boolean |
check.type.http.port | Target port | Integer |
check.type.http.username | Username for target HTTP authentication | String |
check.type.http.password | Password for target HTTP authentication | String |
check.type.http.shouldcontain | Target site should contain this string | String |
check.type.http.shouldnotcontain | Target site should NOT contain this string | String |
check.type.http.postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String |
check.type.http.requestheaders.* | Custom HTTP header. Entry value should match header name | String or List |
HTTP Custom attributes
Attribute | Description | Type |
---|---|---|
check.type.httpcustom.url | Path to target XML file on server | String |
check.type.httpcustom.encryption | Connection encryption | Boolean |
check.type.httpcustom.port | Target port | Integer |
check.type.http.username | Username for target HTTP authentication | String |
check.type.http.password | Password for target HTTP authentication | String |
check.type.httpcustom.additionalurls.(entry) | Full URL (including hostname) to target additional XML file. | String |
TCP attributes
Attribute | Description | Type |
---|---|---|
check.type.tcp.port | Target port | Integer |
check.type.tcp.stringtosend | String to send | String |
check.type.tcp.stringtoexpect | String to expect in response | String |
Ping attributes
Attribute | Description | Type |
---|
DNS attributes
Attribute | Description | Type |
---|---|---|
check.type.dns.nameserver | DNS server to use | String |
check.type.dns.expectedip | Expected IP | String |
UDP attributes
Attribute | Description | Type |
---|---|---|
check.type.udp.port | Target port | Integer |
check.type.udp.stringtosend | String to send | String |
check.type.udp.stringtoexpect | String to expect in response | String |
SMTP attributes
Attribute | Description | Type |
---|---|---|
check.type.smtp.port | Target port | Integer |
check.type.smtp.username | Username for target SMTP authentication | String |
check.type.smtp.password | Password for target SMTP authentication | String |
check.type.smtp.encryption | Connection encryption | Boolean |
check.type.smtp.stringtoexpect | String to expect in response | String |
POP3 attributes
Attribute | Description | Type |
---|---|---|
check.type.pop3.port | Target port | Integer |
check.type.pop3.encryption | Connection encryption | Boolean |
check.type.pop3.stringtoexpect | String to expect in response | String |
IMAP attributes
Attribute | Description | Type |
---|---|---|
check.type.imap.port | Target port | Integer |
check.type.imap.encryption | Connection encryption | Boolean |
check.type.imap.stringtoexpect | String to expect in response | String |
Examples
Get detailed information about check 85975
Request
GET /api/2.1/checks/85975
Response
{ "check" : { "id" : 85975, "name" : "My check 7", "resolution" : 1, "sendnotificationwhendown" : 0, "notifyagainevery" : 0, "notifywhenbackup" : false, "created" : 1240394682, "type" : { "http" : { "url" : "/", "port" : 80, "requestheaders" : { "User-Agent" : "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)" "Cookie": ["sessionid=123", "lastvisited=1293142347"] } } }, "hostname" : "s7.mydomain.com", "status" : "up", "lasterrortime" : 1293143467, "lasttesttime" : 1294064823 } }
Method: Create New Check
Description
Creates a new check with settings specified by provided parameters.
URL Syntax
/api/2.1/checks
HTTP Method
POST
Successful HTTP Response
200
Parameters
General parameters for ALL new checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Check name | String | yes | |
host | Target host | String | yes | |
type | Type of check | String (http, httpcustom, tcp, ping, dns, udp, smtp, pop3, imap) | yes | |
paused | Paused | Boolean | no | false |
resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | 5 |
userids | User identifiers. For example userids=154325,465231,765871 | Comma separated Integers | no | |
sendnotificationwhendown | Send notification when down n times | Integer | no | 2 |
notifyagainevery | Notify again every n result. 0 means that no extra notifications will be sent. | Integer | no | 0 |
notifywhenbackup | Notify when back up again | Boolean | no | true |
tags | Check tags | Comma separated strings | no | |
probe_filters | Filters used for probe selections. Overwrites previous filters for check. To remove all filters from a check, use an empty value | Comma separated key:value pairs | no | |
ipv6 | Use ipv6 instead of ipv4, if an IP address is provided as host this will be overrided by the IP address version | Boolean | no | |
responsetime_threshold | Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) | Integer | no | 30000 |
integrationids | Integration identifiers. For example integrationids=11,22,33 | Comma separated Integers | no | |
teamids | Teams to alert | Comma separated Integers | no |
Type-specific parameters for HTTP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path on server | String | no | / |
encryption | Connection encryption | Boolean | no | false |
port | Target port | Integer | no | 80 |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
shouldcontain | Target site should contain this string. | String | no | |
shouldnotcontain | Target site should NOT contain this string. If shouldcontain is also set, this parameter is not allowed. | String | no | |
postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheadername1=My-Header:CoolValue | String | no |
Type-specific parameters for HTTP Custom checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path to XML file on server | String | yes | |
encryption | Connection encryption | Boolean | no | false |
port | Target port | Integer | no | 80 |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
Type-specific parameters for TCP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | yes | |
stringtosend | String to send | String | no | |
stringtoexpect | String to expect in response | String | no |
Type-specific parameters for Ping checks
Parameter name | Description | Type | Mandatory | Default |
---|
Type-specific parameters for DNS checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
expectedip | Expected ip | String | yes | |
nameserver | Nameserver | String | yes |
Type-specific parameters for UDP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | yes | |
stringtosend | String to send | String | yes | |
stringtoexpect | String to expect in response | String | yes |
Type-specific parameters for SMTP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 25 |
auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Type-specific parameters for POP3 checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 110 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Type-specific parameters for IMAP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 143 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Response Attributes
Attribute | Description | Type |
---|---|---|
check.id | New check identifier | Integer |
check.name | New check name | String |
Examples
Create a new HTTP check for www.mydomain.com with default settings
Request
POST /api/2.1/checks
body:
name=My+new+HTTP+check&type=http&host=www.mydomain.com
Response
{ "check":{ "id":138631, "name":"My new HTTP check" } }
Create a new SMTP check for smtp.mymailserver.com with SSL/TLS encryption, provided user/password, 15 minutes check resolution, with SMS and email alerts to contacts 123456 and 789012 after 1 down result
Request
POST /api/2.1/checks
body:
name=My+new+SMTP+check&type=smtp&resolution=15&sendnotificationwhendown=1&userids=123456,789012&host=smtp.mymailserver.com&auth=myuser%3Amypassword&encryption=true
Response
{ "check":{ "id":138632, "name":"My new SMTP check" } }
Method: Modify Check
Description
Modify settings for a check. The provided settings will overwrite previous values. Settings not provided will stay the same as before the update. To clear an existing value, provide an empty value. Please note that you cannot change the type of a check once it has been created.
URL Syntax
/api/2.1/checks/{checkid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
General parameters for ALL checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Check name | String | no | |
host | Target host | String | no | |
paused | Paused | Boolean | no | |
resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | |
userids | User identifiers. For example userids=154325,465231,765871 | Comma separated Integers | no | |
sendnotificationwhendown | Send notification when down n times | Integer | no | |
notifyagainevery | Notify again every n result. 0 means that no extra notifications will be sent. | Integer | no | |
notifywhenbackup | Notify when back up again | Boolean | no | |
checkids | Specify which checks to bulk modify, comma separated list. | Comma separated integers | no | |
tags | Check tags. Overwrites previous tags for check To remove all tags from a check, use an empty value | Comma separated strings | no | |
addtags | Check tags to add in addition to current check tags | Comma separated strings | no | |
probe_filters | Filters used for probe selections. Overwrites previous filters for check. To remove all filters from a check, use an empty value | Comma separated strings | no | |
ipv6 | Use ipv6 instead of ipv4, if an IP address is provided as host this will be overrided by the IP address version | Boolean | no | |
responsetime_threshold | Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) | Integer | no | 30000 |
integrationids | Integration identifiers. For example integrationids=11,22,33 | Comma separated Integers | no | |
teamids | Teams to alert | Comma separated Integers | no |
Type-specific parameters for HTTP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path on server | String | no | |
encryption | Connection encryption | Boolean | no | |
port | Target port | Integer | no | |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
shouldcontain | Target site should contain this string | String | no | |
shouldnotcontain | Target site should NOT contain this string. If shouldcontain is also set, this parameter is not allowed. | String | no | |
postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheadername1=My-Header:CoolValue | String | no |
Type-specific parameters for HTTP Custom checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path to XML file on server | String | no | |
encryption | Connection encryption | Boolean | no | |
port | Target port | Integer | no | |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
Type-specific parameters for TCP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | |
stringtosend | String to send | String | no | |
stringtoexpect | String to expect in response | String | no |
Type-specific parameters for Ping checks
Parameter name | Description | Type | Mandatory | Default |
---|
Type-specific parameters for DNS checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
expectedip | Expected ip | String | no | |
nameserver | Nameserver | String | no |
Type-specific parameters for UDP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | |
stringtosend | String to send | String | no | |
stringtoexpect | String to expect in response | String | no |
Type-specific parameters for SMTP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | |
auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no |
Type-specific parameters for POP3 checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 110 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no |
Type-specific parameters for IMAP checks
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 143 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Change user/password and resolution on SMTP check 138632
Request
PUT /api/2.1/checks/138632
body:
auth=newuser%3Anewpassword&resolution=30
Response
{ "message":"Modification of check was successful!" }
Pause check 138632
Request
PUT /api/2.1/checks/138632
body:
paused=true
Response
{ "message":"Modification of check was successful!" }
Method: Modify Multiple Checks
Description
Pause or change resolution for multiple checks in one bulk call.
URL Syntax
/api/2.1/checks
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
paused | Paused | Boolean | no | |
resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | |
checkids | Comma-separated list of identifiers for checks to be modified. Invalid check identifiers will be ignored. | String | no | All checks |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Pause all checks
Request
PUT /api/2.1/checks
body:
paused=true
Response
{ "message" : "Modification of 4 checks was successful!" }
Resume all checks
Request
PUT /api/2.1/checks
body:
paused=false
Response
{ "message" : "Modification of 4 checks was successful!" }
Method: Delete Check
Description
Deletes a check. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
URL Syntax
/api/2.1/checks/{checkid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Permanently delete check 134536
Request
DELETE /api/2.1/checks/134536
Response
{ "message":"Deletion of check was successful!" }
Method: Delete Multiple Checks
Description
Deletes a list of checks. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
URL Syntax
/api/2.1/checks
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
delcheckids | Comma-separated list of identifiers for checks to be deleted. | String | yes |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Permanently delete checks 134536, 134539 and 134551
Request
DELETE /api/2.1/checks
body:
delcheckids=134536,134539,134551
Response
{ "message":"Deletion of checks was successful!" }
Resource: Credits
Method: Get Credits List
Description
Returns information about remaining checks, SMS credits and SMS auto-refill status.
URL Syntax
/api/2.1/credits
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
credits.checklimit | Total number of check slots on this account | Integer |
credits.availablechecks | Free check slots available for new checks | Integer |
credits.useddefault | Total number of default check slots | Integer |
credits.usedtransaction | Total number of transaction check slots | Integer |
credits.availablesms | SMS credits remaining on this account | Integer |
credits.availablesmstests | SMS provider tests remaining on this account | Integer |
credits.autofillsms | Auto fill SMS | Boolean |
credits.autofillsms_amount | The amount of sms to purchase when "autofillsms_when_left" is triggered | Integer |
credits.autofillsms_when_left | The amount of sms left that is going to trigger purchase of sms | Integer |
credits.max_sms_overage | The amount of overage SMSes that may be used, or null if SMS overage is not enabled. | Integer |
credits.availablerumsites | Open RUM site slots available | Integer |
credits.usedrumsites | Number of used RUM sites | Integer |
credits.maxrumfilters | Number of maximum rum filters | Integer |
credits.maxrumpageviews | Number of maximum pageviews per month | Integer |
Examples
Get credits list
Request
GET /api/2.1/credits
Response
{ "credits": { "checklimit": 18, "availablechecks": 5, "useddefault": 6, "usedtransaction": 7, "availablesms": 20, "availablesmstests": 7, "autofillsms": false, "autofillsms_amount": 0, "autofillsms_when_left": 0, "max_sms_overage": 50, "availablerumsites": 4, "usedrumsites": 1, "maxrumfilters": 10, "maxrumpageviews": 100000 } }
Resource: Maintenance
Method: Get maintenance windows list
Description
Returns a list of user's maintenance windows.
URL Syntax
/api/2.1/maintenance
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
limit | Count of items to list. | Integer | no | |
offset | Offset of the list. | Integer | no | |
orderby | Order by the specific property of the maintenance window. | String('description', from', 'to', 'effectiveto') | no | |
order | Order a-z for asc z-a for desc. | String('asc', 'desc') | no | 'asc' |
Response Attributes
Attribute | Description | Type |
---|---|---|
maintenance | A list of maintenance windows | Array |
maintenance.(entry) | Maintenance window body | Object |
maintenance.(entry).id | Maintenance window identifier | Integer |
maintenance.(entry).description | Description | String |
maintenance.(entry).from | Initial maintenance window start. Format UNIX time. | Integer |
maintenance.(entry).to | Initial maintenance window end. Format UNIX time. | Integer |
maintenance.(entry).recurrencetype | Type of recurrence. | String('none', 'day', 'week', 'month') |
maintenance.(entry).repeatevery | Repeat every n-th day/week/month | Integer |
maintenance.(entry).effectiveto | Recurrence end. Format UNIX time. | Integer |
maintenance.(entry).checks | Connected checks | Object |
maintenance.(entry).checks.tms | List of connected Transaction checks | Array |
maintenance.(entry).checks.tms.(entry) | Id of connected Transaction check | Integer |
maintenance.(entry).checks.uptime | List of connected Uptime checks | Array |
maintenance.(entry).checks.uptime.(entry) | Id of connected Uptime check | Integer |
Examples
Get all user's maintenance windows
Request
GET /api/2.1/maintenance
Response
{ "maintenance": [ { "id": 1, "description": "Maintenance window from DB", "from": 1497520800, "to": 1497574800, "recurrencetype": "none", "repeatevery": 0, "effectiveto": 1497574800, "checks": { "uptime": [506206, 506233, 222], "tms": [123, 111] } }, { "id": 2, "description": "Another maintenance window from DB", "from": 1497574800, "to": 1497578400, "recurrencetype": "none", "repeatevery": 0, "effectiveto": 1497578400, "checks": { "uptime": [], "tms": [] } } ] }
Method: Get maintenance window detail
Description
Returns the maintenance window specified by its id.
URL Syntax
/api/2.1/maintenance/{id}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
maintenance.id | Maintenance window identifier | Integer |
maintenance.description | Description | String |
maintenance.from | Initial maintenance window start. Format UNIX time. | Integer |
maintenance.to | Initial maintenance window end. Format UNIX time. | Integer |
maintenance.recurrencetype | Type of recurrence. | String('none', 'day', 'week', 'month') |
maintenance.repeatevery | Repeat every n-th day/week/month | Integer |
maintenance.effectiveto | Recurrence end. Format UNIX time. | Integer |
maintenance.checks | Connected checks | Object |
maintenance.checks.tms | List of connected TMS checks | Array |
maintenance.checks.tms.(entry) | Id of connected TMS check | Integer |
maintenance.checks.uptime | List of connected Uptime checks | Array |
maintenance.checks.uptime.(entry) | Id of connected Uptime check | Integer |
Examples
Get maintenance window detail
Request
GET /api/2.1/maintenance/456
Response
{ "maintenance": { "id": 456, "description": "Particular maintenance window", "from": 1497520800, "to": 1497574800, "recurrencetype": "none", "repeatevery": 0, "effectiveto": 1497574800, "checks": { "uptime": [506206, 506233, 222], "tms": [123, 111] } } }
Method: Create new maintenance window
Description
Create new maintenance window.
URL Syntax
/api/2.1/maintenance
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
description | Description | String | yes | |
from | Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | yes | |
to | Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | yes | |
recurrencetype | Type of recurrence. | String('none', 'day', 'week', 'month') | no | 'none' |
repeatevery | Repeat every n-th day/week/month | Integer | no | 0 |
effectiveto | Recurrence end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | no | Equal to `to` |
uptimeids | Identifiers of uptime checks to assign to the maintenance window | Comma separated Integers | no | |
tmsids | Identifiers of transaction checks to assign to the maintenance window | Comma separated Integers | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
maintenance.id | Unique id of the new maintenance window | Integer |
Examples
Create new maintenance window
Request
POST /api/2.1/maintenance
body:
description=Some%20description%20of%20the%20maintenance%20window&from=1500471702&to=1500475302
Response
{ "maintenance": { "id": 666 } }
Method: Modify the maintenance window
Description
Modify the maintenance window.
URL Syntax
/api/2.1/maintenance/{id}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
description | Description | String | no | |
from | Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | yes | |
to | Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | yes | |
recurrencetype | Type of recurrence. | String('none', 'day', 'week', 'month') | no | 'none' |
repeatevery | Repeat every n-th day/week/month | Integer | no | 0 |
effectiveto | Recurrence end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | no | Equal to `to` |
uptimeids | Identifiers of uptime checks to assign to the maintenance window | Comma separated Integers | no | |
tmsids | Identifiers of transaction checks to assign to the maintenance window | Comma separated Integers | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Modification result description | String |
Examples
Modify the maintenance window
Request
PUT /api/2.1/maintenance/12345
body:
description=Modified%20maintenance%20window
Response
{ "message": "Maintenance window successfully modified!" }
Method: Delete the maintenance window
Description
Delete the maintenance window. Note that only future maintenance window can be deleted.
URL Syntax
/api/2.1/maintenance/{id}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Result description | String |
Examples
Delete the maintenance window 12345
Request
DELETE /api/2.1/maintenance/12345
Response
{ "message": "Maintenance window successfully deleted!" }
Method: Delete multiple maintenance windows
Description
Delete multiple maintenance windows. Note that only future maintenance windows can be deleted.
URL Syntax
/api/2.1/maintenance
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
maintenanceids | Comma-separated list of identifiers of maintenance windows to be deleted. | String | yes |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Result description | String |
Examples
Delete the maintenance windows 1, 2, 3, 4 and 5
Request
DELETE /api/2.1/maintenance
body:
maintenanceids=1,2,3,4,5
Response
{ "message":"5 maintenance windows successfully deleted." }
Resource: Maintenance occurrences
Method: Get maintenance occurrence.
Description
Gets a maintenance occurrence details specified by its identifier.
URL Syntax
/api/2.1/maintenance.occurrences/{id}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
id | Identifier of an occurence. | Integer |
maintenanceid | Identifier of the related maintenance window. | Integer |
from | Beginning of the occurrence. Format UNIX timestamp. | Integer |
to | The end of the occurrence. Format UNIX timestamp. | Integer |
Examples
Get the detail of occurrence 57
Request
GET /api/2.1/maintenance.occurrences/57
Response
{ "occurrence": { "id": 57, "maintenanceid": 44, "from": 1501714800, "to": 1501719300 } }
Method: Get maintenance occurrences list
Description
Returns a list of maintenance occurrences.
URL Syntax
/api/2.1/maintenance.occurrences
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
maintenanceid | Maintenance window identifier. (List only occurrences of a specific maintenance window.) | Integer | no | |
from | Effective from (unix timestamp). (List occurrences which are effective from the specified unix timestamp. If not specified, current timestamp is used.) | Integer | no | Current timestamp |
to | Effective to (unix timestamp). (List occurrences which are effective to the specified unix timestamp.) | Integer | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
occurrences | A list of maintenance occurrences. | Array |
occurrences.(entry) | Maintenance occurrence. | Object |
occurrences.(entry).id | Identifier of an occurence. | Integer |
occurrences.(entry).maintenanceid | Identifier of the related maintenance window. | Integer |
occurrences.(entry).from | Beginning of the occurrence. Format UNIX timestamp. | Integer |
occurrences.(entry).to | The end of the occurrence. Format UNIX timestamp. | Integer |
Examples
Get the occurrences of the maintenance windows 44 that are effective from 2017-08-02T00:00:00 to 2017-08-02T23:59:59
Request
GET /api/2.1/maintenance.occurrences?maintenanceid=44&from=1501632000&to=1501718399
Response
{ "occurrences": [ { "id": 455, "maintenanceid": 44, "from": 1501628400, "to": 1501632900, }, { "id": 456, "maintenanceid": 44, "from": 1501714800, "to": 1501719300, } ] }
Method: Modify maintenance occurrence
Description
Modifies a maintenance occurrence specified by its identifier.
URL Syntax
/api/2.1/maintenance.occurrences/{id}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Beginning of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | no | |
to | End of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) | Integer | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Modification result description | String |
Examples
Modify the maintenance occurrence 666
Request
PUT /api/2.1/maintenance.occurrences/666
body:
from=1500471702&to=1500475302
Response
{ "message": "Occurrence successfully modified!" }
Method: Delete maintenance occurrence.
Description
Deletes the maintenance occurrence specified by its identifier. Note that only future occurrences can be deleted.
URL Syntax
/api/2.1/maintenance.occurrences/{id}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Result description | String |
Examples
Delete the maintenance window occurrence 666
Request
DELETE /api/2.1/maintenance.occurrences/666
Response
{ "message": "Occurrence successfully deleted!" }
Method: Delete multiple maintenance occurrences.
Description
Deletes multiple maintenance occurrences specified by their identifiers. Note that only future occurrences can be deleted.
URL Syntax
/api/2.1/maintenance.occurrences
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
occurrenceids | Comma-separated list of identifiers of maintenance occurrences to delete. | String | yes |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Result description | String |
Examples
Delete the occurrences 1, 2, 3, 4 and 5
Request
DELETE /api/2.1/maintenance.occurrences
body:
occurrenceids=1,2,3,4,5
Response
{ "message":"5 occurrences successfully deleted." }
Resource: Probes
Method: Get Probe Server List
Description
Returns a list of all Pingdom probe servers for Uptime and Transaction checks.
URL Syntax
/api/2.1/probes
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
limit | Limits the number of returned probes to the specified quantity. | Integer | no | |
offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
onlyactive | Return only active probes. | Boolean | no | false |
onlytms | Return only active transaction monitor probes. | Boolean | no | false |
includedeleted | Include old probes that are no longer in use | Boolean | no | false |
Response Attributes
Attribute | Description | Type |
---|---|---|
probes | A list of probes | Array |
probes.(entry) | Probe body | Object |
probes.(entry).id | Unique probe id | Integer |
probes.(entry).country | Country | String |
probes.(entry).city | City | String |
probes.(entry).name | Name | String |
probes.(entry).active | Is the probe currently active? | Boolean |
probes.(entry).hostname | DNS name | String |
probes.(entry).ip | IPv4 address | String |
probes.(entry).ipv6 | IPv6 address (not all probes have this) | String |
probes.(entry).countryiso | Country ISO code | String |
Examples
Get all (existing) probes
Request
GET /api/2.1/probes
Response
{ "probes":[ { "id":1, "country":"United Kingdom", "city":"Manchester", "name":"Manchester, UK", "active":true, "hostname":"s424.pingdom.com", "ip":"212.84.74.156", "countryiso":"GB" }, { "id":2, "country":"United States", "city":"New York", "name":"New York, NY", "active":true, "hostname":"s413.pingdom.com", "ip":"70.32.40.2" "countryiso":"US" }, { "id":3, "country":"Denmark", "city":"Copenhagen", "name":"Copenhagen, Denmark", "active":true, "hostname":"s416.pingdom.com", "ip":"82.103.128.63" "countryiso":"DK" } ] }
Resource: Reference
Method: Get Reference
Description
Get a reference of regions, timezones and date/time/number formats and their identifiers.
URL Syntax
/api/2.1/reference
HTTP Method
GET
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
regions.id | Region identifier | Integer |
regions.description | Region description | String |
regions.countryid | Corresponding country identifier | Integer |
regions.datetimeformatid | Corresponding datetimeformat identifier | Integer |
regions.numberformatid | Corresponding numberformat identifier | Integer |
regions.timezoneid | Corresponding timezone identifier | Integer |
timezones.id | Time zone identifier | Integer |
timezones.description | Time zone description | String |
datetimeformats.id | Date/time format identifier | Integer |
datetimeformats.description | Date/time format description | String |
numberformats.id | Number format identifier | Integer |
numberformats.description | Number format description | String |
countries.id | Country id | Integer |
countries.iso | Country ISO code | String |
countries.name | Country name | String |
phonecodes.countryid | Country id (Can be mapped against countries.id) | Integer |
phonecodes.name | Country name | String |
phonecodes.phonecode | Area phone code | String |
Examples
Request
GET /api/2.1/reference
Response
{ "regions" : [ { "id" : 2, "description" : "United States (Alaska)" }, { "id" : 1, "description" : "United States (Hawaii)" }, { "id" : 3, "description" : "United States (Pacific Time)" }, { "id" : 4, "description" : "United States (Mountain Time)" }, { "id" : 5, "description" : "United States (Central Time)" }, { "id" : 6, "description" : "United States (Eastern Time)" }, { "id" : 7, "description" : "Sweden" }, { "id" : 8, "description" : "United Kingdom" }, { "id" : 9, "description" : "India" }, { "id" : 10, "description" : "Canada (Pacific Time)" }, { "id" : 11, "description" : "Canada (Mountain Time)" }, { "id" : 12, "description" : "Canada (Central Time)" }, { "id" : 13, "description" : "Canada (Eastern Time)" }, { "id" : 14, "description" : "Canada (Atlantic Time)" }, { "id" : 15, "description" : "Canada (Newfoundland)" }, { "id" : 16, "description" : "China" }, { "id" : 17, "description" : "Australia (Adelaide)" }, { "id" : 18, "description" : "Australia (Canberra, Melbourne, Sydney)" }, { "id" : 19, "description" : "Turkey" }, { "id" : 20, "description" : "Spain" }, { "id" : 21, "description" : "Brazil (Eastern Time)" }, { "id" : 22, "description" : "Brazil (Atlantic Time)" }, { "id" : 23, "description" : "Brazil (Brazil, Buenos Aires, Georgetown)" }, { "id" : 24, "description" : "Brazil (Mid-Atlantic)" }, { "id" : 25, "description" : "Indonesia (Bangkok, Hanoi, Jakarta)" }, { "id" : 26, "description" : "Indonesia (Beijing, Perth, Singapore, Hong Kong)" }, { "id" : 27, "description" : "Indonesia (Tokyo, Seoul, Osaka)" }, { "id" : 28, "description" : "Romania" }, { "id" : 29, "description" : "Mexico (Pacific Time)" }, { "id" : 30, "description" : "Mexico (Mountain Time)" }, { "id" : 31, "description" : "Mexico (Central Time)" }, { "id" : 32, "description" : "Bulgaria" }, { "id" : 33, "description" : "Portugal (Azores)" }, { "id" : 34, "description" : "Portugal (Western Europe Time, London, Lisbon)" }, { "id" : 35, "description" : "Egypt" }, { "id" : 36, "description" : "Italy" }, { "id" : 37, "description" : "Pakistan" }, { "id" : 38, "description" : "France" }, { "id" : 39, "description" : "New Zealand" }, { "id" : 40, "description" : "Australia (Lord Howe Island)" }, { "id" : 41, "description" : "New Zealand (Chatham Islands)" }, { "id" : 42, "description" : "Germany" }, { "id" : 43, "description" : "Saudi Arabia" }, { "id" : 44, "description" : "Australia (Perth)" } ], "timezones" : [ { "id" : 1, "description" : "(GMT -12:00) Eniwetok, Kwajalein" }, { "id" : 2, "description" : "(GMT -11:00) Midway Island, Samoa" }, { "id" : 3, "description" : "(GMT -10:00) Hawaii" }, { "id" : 4, "description" : "(GMT -9:00) Alaska" }, { "id" : 5, "description" : "(GMT -8:00) Pacific Time (US & Canada)" }, { "id" : 6, "description" : "(GMT -7:00) Mountain Time (US & Canada)" }, { "id" : 7, "description" : "(GMT -6:00) Central Time (US & Can.), Mexico" }, { "id" : 8, "description" : "(GMT -5:00) Eastern Time (US & Can.)" }, { "id" : 9, "description" : "(GMT -4:00) Atlantic Time (Can.)" }, { "id" : 10, "description" : "(GMT -3:30) Newfoundland" }, { "id" : 11, "description" : "(GMT -3:00) Brazil, Buenos Aires, Georgetown" }, { "id" : 12, "description" : "(GMT -2:00) Mid-Atlantic" }, { "id" : 13, "description" : "(GMT -1:00 hour) Azores" }, { "id" : 14, "description" : "(GMT) Western Europe Time, London, Lisbon" }, { "id" : 15, "description" : "(GMT +1:00 hour) Brussels, Copenhagen, Madrid" }, { "id" : 16, "description" : "(GMT +2:00) Athens, Cairo" }, { "id" : 17, "description" : "(GMT +3:00) Baghdad, Moscow, Riyadh" }, { "id" : 18, "description" : "(GMT +3:30) Tehran" }, { "id" : 19, "description" : "(GMT +4:00) Abu Dhabi, Muscat" }, { "id" : 20, "description" : "(GMT +4:30) Kabul" }, { "id" : 21, "description" : "(GMT +5:00) Islamabad, Karachi" }, { "id" : 22, "description" : "(GMT +5:30) Bombay, Calcutta, Colombo, New Delhi" }, { "id" : 23, "description" : "(GMT +6:00) Almaty, Dhaka" }, { "id" : 24, "description" : "(GMT +7:00) Bangkok, Hanoi, Jakarta" }, { "id" : 25, "description" : "(GMT +8:00) Beijing, Perth, Singapore, Hong Kong" }, { "id" : 26, "description" : "(GMT +9:00) Tokyo, Seoul, Osaka" }, { "id" : 27, "description" : "(GMT +9:30) Adelaide" }, { "id" : 28, "description" : "(GMT +10:00) Canbera, Melbourne, Sydney" }, { "id" : 29, "description" : "(GMT +11:00) Solomon Isl., New Caledonia" }, { "id" : 30, "description" : "(GMT +12:00) Auckland, Fiji, Kamchatka" }, { "id" : 32, "description" : "(GMT +10:30) Lord Howe Island" }, { "id" : 33, "description" : "(GMT +12:45) Chatham Islands" }, { "id" : 34, "description" : "(GMT +10:00) Brisbane" }, { "id" : 35, "description" : "(GMT +13:00) New Zealand Daylight Time, Tonga" }, { "id" : 36, "description" : "(GMT) Reykjavik" }, { "id" : 37, "description" : "(GMT +2:00) South African Standard Time" }, { "id" : 38, "description" : "(GMT -4:30) Caracas" }, { "id" : 39, "description" : "(GMT -6:00) Central America, El Salvador" } ], "datetimeformats" : [ { "id" : 1, "description" : "07/31/2006 02:45:05pm" }, { "id" : 2, "description" : "31/07/2006 02:45:05pm" }, { "id" : 3, "description" : "31/07/2006 14:45:05" }, { "id" : 4, "description" : "2006-07-31 14:45:05" }, { "id" : 5, "description" : "31.07.2006. 14:45:05" }, { "id" : 6, "description" : "31/07/2006 14h45m05" }, { "id" : 7, "description" : "31-07-2006 02:45:05pm" }, { "id" : 8, "description" : "31-07-2006 14:45:05" } ], "numberformats" : [ { "id" : 1, "description" : "123,456,789.00" }, { "id" : 2, "description" : "123 456 789.00" }, { "id" : 3, "description" : "123456789.00" }, { "id" : 4, "description" : "123.456.789,00" }, { "id" : 5, "description" : "123 456 789,00" }, { "id" : 6, "description" : "123456789,00" } ] }
Resource: Reports.email
Method: Get Email Report Subscription List
Description
Returns a list of email report subscriptions.
URL Syntax
/api/2.1/reports.email
HTTP Method
GET
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
subscriptions.(entry).id | Subscription identifier | Integer |
subscriptions.(entry).name | Subscription name | String |
subscriptions.(entry).type | Subscription type | String |
subscriptions.(entry).checkid | Check identifier for check subscriptions | String |
subscriptions.(entry).frequency | Report frequency | String |
subscriptions.(entry).additionalemails.(entry) | Additional receiving email | String |
subscriptions.(entry).include_paused | Should include paused checks or not | Boolean |
Examples
Request
GET /api/2.1/reports.email
Response
{ "subscriptions" : [ { "id" : 114979, "name" : "My subscription", "type" : "overview", "frequency" : "monthly", "include_paused": 1 } ] }
Method: Create Email Report
Description
Creates a new email report.
URL Syntax
/api/2.1/reports.email
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | yes | |
checkid | Check identifier. If omitted, this will be an overview report | Integer | no | |
frequency | Report frequency | String (monthly, weekly, daily) | no | monthly |
additionalemails | Comma separated list of additional receiving emails | String | no | |
include_paused | Should include paused checks or not | Boolean | no | true |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
POST /api/2.1/reports.email
body:
name=My+subscription&frequency=weekly&userids=123456,134253
Response
{ "message":"Subscription added" }
Method: Modify Email Report
Description
Modify an email report.
URL Syntax
/api/2.1/reports.email/{reportid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | no | |
checkid | Check identifier. If omitted, this will be an overview report | Integer | no | |
frequency | Report frequency | String (monthly, weekly, daily) | no | |
additionalemails | Comma separated list of additional receiving emails | String | no | |
include_paused | Should include paused checks or not | Boolean | no | true |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
PUT /api/2.1/reports.email/634253
body:
name=My+subscription+modified&frequency=monthly
Response
{ "message":"Subscription modified" }
Method: Delete Email Report
Description
Delete an email report.
URL Syntax
/api/2.1/reports.email/{reportid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
DELETE /api/2.1/reports.email/634253
Response
{ "message":"Subscription deleted" }
Resource: Reports.public
Method: Get Public Report List
Description
Returns a list of public (web-based) reports.
URL Syntax
/api/2.1/reports.public
HTTP Method
GET
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
public.(entry).checkid | Check identifier | Integer |
public.(entry).checkname | Check name | String |
public.(entry).reporturl | URL to report | String |
Examples
Request
GET /api/2.1/reports.public
Response
{ "public" : [ { "checkid" : 85975, "checkname" : "ubuntu packages", "reporturl" : "http://www.pingdom.com/reports/rwknj2rkd39h/check_overview/?name=ubuntu+packages" } ] }
Method: Publish Public Report
Description
Activate public report for a specified check.
URL Syntax
/api/2.1/reports.public/{checkid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
PUT /api/2.1/reports.public/123456
Response
{ "message":"Check published" }
Method: Withdraw Public Report
Description
Deactivate public report for a specified check.
URL Syntax
/api/2.1/reports.public/{checkid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
DELETE /api/2.1/reports.public/123456
Response
{ "message":"Check unpublished" }
Resource: Reports.shared
Method: Get Shared Reports (Banners) List
Description
Returns a list of shared reports (banners).
URL Syntax
/api/2.1/reports.shared
HTTP Method
GET
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
shared.banners.(entry).id | Banner identifier | Integer |
shared.banners.(entry).name | Banner name | String |
shared.banners.(entry).checkid | Check identifier | Integer |
shared.banners.(entry).auto | Automatic period activated? | Boolean |
shared.banners.(entry).type | Banner type | String (response, uptime) |
shared.banners.(entry).url | Banner URL | String |
shared.banners.(entry).fromyear | Period start: year | Integer |
shared.banners.(entry).frommonth | Period start: month | Integer |
shared.banners.(entry).fromday | Period start: day | Integer |
shared.banners.(entry).toyear | Period end: year | Integer |
shared.banners.(entry).tomonth | Period end: month | Integer |
shared.banners.(entry).today | Period end: day | Integer |
Examples
Request
GET /api/2.1/reports.shared
Response
{ "shared" : { "banners" : [ { "id" : "9338512f", "name" : "mydomain.com", "checkid" : 241688, "auto" : true, "type" : "uptime", "url" : "http://share.pingdom.com/banners/9338512f" }, { "id" : "476a37ba", "name" : "myotherdomain.com", "checkid" : 241688, "auto" : true, "type" : "uptime", "url" : "http://share.pingdom.com/banners/476a37ba" } ] } }
Method: Create Shared Report (Banner)
Description
Create a shared report (banner).
URL Syntax
/api/2.1/reports.shared
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
sharedtype | Shared report type. For now, only "banner" is valid | String (banner) | yes | |
checkid | Identifier of target check | Integer | yes | |
auto | Automatic period (If false, requires: fromyear, frommonth, fromday, toyear, tomonth, today) | Boolean | no | true |
fromyear | Period start: year | Integer | no | |
frommonth | Period start: month | Integer | no | |
fromday | Period start: day | Integer | no | |
toyear | Period end: year | Integer | no | |
tomonth | Period end: month | Integer | no | |
today | Period end: day | Integer | no | |
type | Banner type | String (uptime, response) | no | uptime |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
POST /api/2.1/reports.shared
body:
sharedtype=banner&checkid=123456
Response
{ "message":"Banner created" }
Method: Delete Shared Report (Banner)
Description
Delete a shared report (banner).
URL Syntax
/api/2.1/reports.shared/{reportid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Request
DELETE /api/2.1/reports.shared/476a37ba
Response
{ "message":"Banner deleted" }
Resource: Results
Method: Get Raw Check Results
Description
Return a list of raw test results for a specified check
URL Syntax
/api/2.1/results/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
to | End of period. Format is UNIX timestamp | Integer | no | current time |
from | Start of period. Format is UNIX timestamp | Integer | no | 1 day prior to 'to' |
probes | Filter to only show results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
status | Filter to only show results with specified statuses. Format is a comma separated list of (down, up, unconfirmed, unknown) | String | no | all statuses |
limit | Number of results to show (Will be set to 1000 if the provided value is greater than 1000) | Integer | no | 1000 |
offset | Number of results to skip (Max value is 43200) | Integer | no | 0 |
includeanalysis | Attach available root cause analysis identifiers to corresponding results | Boolean | no | false |
maxresponse | Maximum response time (ms). If set, specified interval must not be larger than 31 days. | Integer | no | |
minresponse | Minimum response time (ms). If set, specified interval must not be larger than 31 days. | Integer | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
results.(entry).probeid | Probe identifier | Integer |
results.(entry).time | Time when test was performed. Format is UNIX timestamp | Integer |
results.(entry).status | Result status | String (up, down, unconfirmed_down, unknown) |
results.(entry).responsetime | Response time (in milliseconds) (Will be 0 if no response was received) | Integer |
results.(entry).statusdesc | Short status description | String |
results.(entry).statusdesclong | Long status description | String |
results.(entry).analysisid | Analysis identifier | Integer |
activeprobes | For your convinience, a list of used probes that produced the showed results | Array |
activeprobes.(entry) | Probe identifier | Integer |
Examples
Get the 5 latest results for check 85975
Request
GET /api/2.1/results/85975?limit=5
Response
{ "results" : [ { "probeid" : 33, "time" : 1294235764, "status" : "up", "responsetime" : 91, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 34, "time" : 1294235703, "status" : "up", "responsetime" : 442, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 35, "time" : 1294235643, "status" : "up", "responsetime" : 187, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 36, "time" : 1294235583, "status" : "up", "responsetime" : 403, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 37, "time" : 1294235523, "status" : "up", "responsetime" : 111, "statusdesc" : "OK", "statusdesclong" : "OK" } ], "activeprobes" : [ 33, 34, 35, 36, 37 ] }
Resource: Servertime
Method: Get Current Server Time
Description
Get the current time of the API server.
URL Syntax
/api/2.1/servertime
HTTP Method
GET
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
servertime | Current server time. Format is UNIX timestamp | Integer |
Examples
Request
GET /api/2.1/servertime
Response
{ "servertime" : 1294237910 }
Resource: Settings
Method: Get Account Settings
Description
Returns all account-specific settings.
URL Syntax
/api/2.1/settings
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
settings.firstname | First name | String |
settings.lastname | Last name | String |
settings.company | Company | String |
settings.email | Account Email | String |
settings.billing_email | Billing Email | String |
settings.phone | Phone | String |
settings.phonecountryiso | Phone country ISO code | String |
settings.cellphone | Cellphone | String |
settings.cellphonecountryiso | Cellphone country ISO code | String |
settings.address | Address line 1 | String |
settings.address2 | Address line 2 | String |
settings.zip | Zip, postal code or equivalent | String |
settings.location | City / location | String |
settings.state | State or equivalent | String |
settings.description | Account description | String |
settings.autologout | Enable auto-logout | Boolean |
settings.country | Country | Object |
settings.country.name | Country name | String |
settings.country.iso | Country ISO-code | String |
settings.country.countryid | Country identifier, see the Reference resource | Integer |
settings.vatcode | For certain EU countries, VAT-code | String |
settings.external_reference | Purchase order or external reference | String |
settings.region | Region | String |
settings.regionid | Region identifier, see the Reference resource | Integer |
settings.accountcreated | Account creation timestamp, UNIX time format | Integer |
settings.timezone | Time zone | Object |
settings.timezone.id | Time zone name | String |
settings.timezone.description | Time zone description | String |
settings.timezone.timezoneid | Corresponding timezone identifier, see the Reference resource | Integer |
settings.dateformat | Date format | String |
settings.timeformat | Time format | String |
settings.datetimeformatid | Time/date format identifier, see the Reference resource | Integer |
settings.numberformat | Number format | String |
settings.numberexample | Example of number presentation | String |
settings.numberformatid | Number format identifier, see the Reference resource | Integer |
settings.publicreports | Public reports settings | String |
settings.publicreports.customdesign | Use custom design for public reports | Boolean |
settings.publicreports.textcolor | Custom text color | String |
settings.publicreports.backgroundcolor | Background color | String |
settings.publicreports.logourl | URL to custom logotype | String |
settings.publicreports.months | Number of months to show | String |
settings.publicreports.showoverview | Enable overview | Boolean |
settings.publicreports.customdomain | Custom domain | String |
settings.publicreportscode | URL code | String |
settings.settingssaved | True if the user has saved initial settings in the control panel | Boolean |
Examples
Request
GET /api/2.1/settings
Response
{ "settings" : { "firstname" : "John", "lastname" : "Smith", "company" : "Pingdom", "email" : "johndoe@pingdom.com", "phone" : "", "cellphone" : "46-555555555", "address" : "Pingdom Street 1", "address2" : "", "zip" : "55555", "location" : "Pingdom City", "state" : "", "external_reference": "", "description" : "My Personal Account", "autologout" : false, "country" : { "name" : "Sweden", "iso" : "SE" }, "region" : "Sweden", "timezone" : { "id" : "CET", "description" : "(GMT +1:00 hour) Brussels, Copenhagen, Madrid" }, "dateformat" : "%Y-%m-%d", "timeformat" : "%H:%M:%S", "numberformat" : ", ", "numberexample" : "123 456 789,00" } }
Method: Modify Account Settings
Description
Modify account-specific settings.
URL Syntax
/api/2.1/settings
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
firstname | First name | String | no | |
lastname | Last name | String | no | |
company | Company | String | no | |
Account Email (Please note that your email is used for authentication purposes such as using this API or logging into the My Pingdom) | String | no | ||
billing_email | Billing Email (Please note that your email is used for authentication purposes such as using this API or logging into the My Pingdom) | String | no | |
cellphone | Cellphone (without country code) (Requires cellcountrycode and cellcountryiso) | String | no | |
cellcountrycode | Cellphone country code, for example 1 (USA) or 46 (Sweden) | Integer | no | |
cellcountryiso | Cellphone country ISO code, for example US (USA) or SE (Sweden) | String | no | |
phone | Phone (without country code) (Requires phonecountrycode and phonecountryiso) | String | no | |
phonecountrycode | Phone country code, for example 1 (USA) or 46 (Sweden) | Integer | no | |
phonecountryiso | Phone country ISO code, for example US (USA) or SE (Sweden) | String | no | |
address | Address line 1 | String | no | |
address2 | Address line 2 | String | no | |
zip | Zip, postal code or equivalent | String | no | |
location | City / location | String | no | |
state | State, province or equivalent | String | no | |
description | Account description | String | no | |
countryiso | Country ISO code, for example US (USA) or SE (Sweden) | String | no | |
vatcode | For certain EU countries, VAT-code. Example: SE123456789 | String | no | |
autologout | Enable auto-logout | Boolean | no | |
regionid | Region identifier, for localization purposes. 0 for "Custom"/none. See the API resource "Reference" for more information | Integer | no | |
timezoneid | Time zone identifier. See the API resource "Reference" for more information | Integer | no | |
datetimeformatid | Date/time format identifier. See the API resource "Reference" for more information | Integer | no | |
numberformatid | Number format identifier. See the API resource "Reference" for more information | Integer | no | |
pubrcustomdesign | Use custom design for public reports | Boolean | no | |
pubrtextcolor | Public reports, custom text color (Example: FEFFFE or 99CC00) | String | no | |
pubrbackgroundcolor | Public reports, background color (Example: FEFFFE or 99CC00) | String | no | |
pubrlogourl | Public reports, URL to custom logotype. This parameter is currently disabled for public use. (Example: stats.pingdom.com/images/logo.png) | String | no | |
pubrmonths | Public reports, number of months to show | String (none, all, 3) | no | |
pubrshowoverview | Public reports, enable overview | Boolean | no | |
pubrcustomdomain | Public reports, custom domain. Must be a DNS CNAME with target stats.pingdom.com | Boolean | no | |
updaterenewal | Update renewal product for accounts with renewal set to PINGDOM_*_TRIAL_ENDED, if they supply enough contact information to be invoiceable (according to swedish law). | Boolean | no | true |
Response Attributes
Attribute | Description | Type |
---|
Examples
Change company name to Pingdom and state to Neverland
Request
PUT /api/2.1/settings
body:
company=Pingdom&state=Neverland
Response
{ "message":"Settings updated successfully" }
Resource: Single
Method: Make A Single Test
Description
Performs a single test using a specified Pingdom probe against a specified target. Please note that this method is meant to be used sparingly, not to set up your own monitoring solution.
URL Syntax
/api/2.1/single
HTTP Method
GET
Successful HTTP Response
200
Parameters
General parameters for ALL single tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
host | Target host | String | yes | |
type | Type of test | String (http, httpcustom, tcp, ping, dns, udp, smtp, pop3, imap) | yes | |
probeid | Probe identifier | Integer | no | A random probe |
probe_filters | Filters used for probe selections. | Comma separated key:value pairs | no | |
ipv6 | Use ipv6 instead of ipv4 | Boolean | no | |
responsetime_threshold | Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) | Integer | no | 30000 |
Type-specific parameters for HTTP tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path on server | String | no | / |
encryption | Connection encryption | Boolean | no | false |
port | Target port | Integer | no | 80 |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
shouldcontain | Target site should contain this string | String | no | |
shouldnotcontain | Target site should NOT contain this string | String | no | |
postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheader1=My-Header:CoolValue | String | no |
Type-specific parameters for HTTP Custom tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
url | Target path to XML file on server | String | yes | |
encryption | Connection encryption | Boolean | no | false |
port | Target port | Integer | no | 80 |
auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
Type-specific parameters for TCP tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | yes | |
stringtosend | String to send | String | no | |
stringtoexpect | String to expect in response | String | no |
Type-specific parameters for Ping tests
Parameter name | Description | Type | Mandatory | Default |
---|
Type-specific parameters for DNS tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
expectedip | Expected ip | String | yes | |
nameserver | Nameserver | String | yes |
Type-specific parameters for UDP tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | yes | |
stringtosend | String to send | String | yes | |
stringtoexpect | String to expect in response | String | yes |
Type-specific parameters for SMTP tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 25 |
auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Type-specific parameters for POP3 tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 110 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Type-specific parameters for IMAP tests
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
port | Target port | Integer | no | 143 |
stringtoexpect | String to expect in response | String | no | |
encryption | Connection encryption | Boolean | no | false |
Response Attributes
Attribute | Description | Type |
---|---|---|
result.status | Test result status | String (up, down) |
result.responsetime | Response time in milliseconds | Integer |
result.statusdesc | Short status description | String |
result.statusdesclong | Long status description | String |
result.probeid | Probe identifier | Integer |
result.probedesc | Probe description | String |
Examples
Request
GET /api/2.1/single?host=pingdom.com&type=http&probeid=17
Response
{ "result" : { "status" : "up", "responsetime" : 73, "statusdesc" : "OK", "statusdesclong" : "OK", "probeid" : 17, "probedesc" : "Stockholm, Sweden" } }
Resource: Summary.average
Method: Get A Response Time / Uptime Average
Description
Get the average time / uptime value for a specified check and time period.
URL Syntax
/api/2.1/summary.average/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Start time of period. Format is UNIX timestamp | Integer | no | 0 |
to | End time of period. Format is UNIX timestamp | Integer | no | current time |
probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
includeuptime | Include uptime information | Boolean | no | false |
bycountry | Split response times into country groups | Boolean | no | false |
byprobe | Split response times into probe groups | Boolean | no | false |
Response Attributes
Attribute | Description | Type |
---|---|---|
summary.responsetime.from | Start time of period | Integer |
summary.responsetime.to | End time of period | Integer |
summary.responsetime.avgresponse | Total average response time in milliseconds | Integer |
summary.responsetime.(entry).countryiso | Country group ISO code | Integer |
summary.responsetime.(entry).probeid | Probe group probe identifier | Integer |
summary.responsetime.(entry).avgresponse | Group average response time in milliseconds | Integer |
summary.status.totalup | Total uptime in seconds (Please note that the accuracy of this value is depending on your check resolution) | Integer |
summary.status.totaldown | Total downtime in seconds (Please note that the accuracy of this value is depending on your check resolution) | Integer |
summary.status.totalunknown | Total unknown/unmonitored/paused in seconds (Please note that the accuracy of this value is depending on your check resolution. Also note that time before the check was created counts as unknown) | Integer |
Examples
Request
GET /api/2.1/summary.average/85975
body:
includeuptime=true
Response
{ "summary" : { "responsetime" : { "from" : 0, "to" : 1294245352, "avgresponse" : 458 }, "status" : { "totalup" : 53072286, "totaldown" : 771879, "totalunknown" : 1240401138 } } }
Request
GET /api/2.1/summary.average/85975
body:
bycountry=true
Response
{ "summary" : { "responsetime" : { "from" : 0, "to" : 1294245226, "avgresponse" : [ { "countryiso" : "SE", "avgresponse" : 250 }, { "countryiso" : "US", "avgresponse" : 650 }, { "countryiso" : "GB", "avgresponse" : 129 }, { "countryiso" : "CA", "avgresponse" : 442 }, { "countryiso" : "NL", "avgresponse" : 162 }, { "countryiso" : "DE", "avgresponse" : 200 }, { "countryiso" : "DK", "avgresponse" : 229 }, { "countryiso" : "FR", "avgresponse" : 204 }, { "countryiso" : "ES", "avgresponse" : 285 } ] } } }
Resource: Summary.hoursofday
Method: Get Response Time Averages For Each Hour Of The Day
Description
Returns the average response time for each hour of the day (0-23) for a specific check over a selected time period. I.e. it shows you what an average day looks like during that time period.
URL Syntax
/api/2.1/summary.hoursofday/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Start time of period. Format is UNIX timestamp | Integer | no | One week earlier than "to" |
to | End time of period. Format is UNIX timestamp | Integer | no | Current time |
probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
uselocaltime | If true, use the user's local time zone for results (from and to parameters should still be specified in UTC). If false, use UTC for results. | Boolean | no | false |
Response Attributes
Attribute | Description | Type |
---|---|---|
hoursofday.(entry).hour | Hour of day (0-23). Please note that if data is missing for an individual hour, it's entry will not be included in the result. | Integer |
hoursofday.(entry).avgresponse | Average response time (in milliseconds) for this hour of the day | Integer |
Examples
Get averages for the last week
Request
GET /api/2.1/summary.hoursofday/85975
Response
{ "hoursofday" : [ { "hour" : 0, "avgresponse" : 259 }, { "hour" : 1, "avgresponse" : 299 }, { "hour" : 2, "avgresponse" : 259 }, { "hour" : 3, "avgresponse" : 327 }, { "hour" : 4, "avgresponse" : 302 }, "hour" : 5, "avgresponse" : 376 }, "hour" : 6, "avgresponse" : 256 }, "hour" : 7, "avgresponse" : 262 }, "hour" : 8, "avgresponse" : 328 }, "hour" : 9, "avgresponse" : 335 }, "hour" : 10, "avgresponse" : 276 }, { "hour" : 11, "avgresponse" : 291 }, { "hour" : 12, "avgresponse" : 287 }, { "hour" : 13, "avgresponse" : 267 }, { "hour" : 14, "avgresponse" : 276 }, { "hour" : 15, "avgresponse" : 266 }, { "hour" : 16, "avgresponse" : 326 }, { "hour" : 17, "avgresponse" : 292 }, { "hour" : 18, "avgresponse" : 301 }, { "hour" : 19, "avgresponse" : 270 }, { "hour" : 20, "avgresponse" : 282 }, { "hour" : 21, "avgresponse" : 262 }, { "hour" : 22, "avgresponse" : 270 }, { "hour" : 23, "avgresponse" : 253 } ] }
Resource: Summary.outage
Method: Get List of Outages
Description
Get a list of status changes for a specified check and time period. If order is speficied to descending, the list is ordered by newest first. (Default is ordered by oldest first.)
URL Syntax
/api/2.1/summary.outage/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Start time of period. Format is UNIX timestamp | Integer | no | One week earlier than to |
to | End time of period. Format is UNIX timestamp | Integer | no | current time |
order | Sorting order of outages. Ascending or descending. | String (asc,desc) | no | asc |
Response Attributes
Attribute | Description | Type |
---|---|---|
summary.states.(entry).status | Interval status | String (up, down, unknown) |
summary.states.(entry).timefrom | Interval start. Format UNIX timestamp | Integer |
summary.states.(entry).timeto | Interval end. Format UNIX timestamp | Integer |
Examples
Request
GET /api/2.1/summary.outage/85975
Response
{ "summary" : { "states" : [ { "status" : "up", "timefrom" : 1293143523, "timeto" : 1294180263 }, { "status" : "down", "timefrom" : 1294180263, "timeto" : 1294180323 }, { "status" : "up", "timefrom" : 1294180323, "timeto" : 1294223466 }, { "status" : "down", "timefrom" : 1294223466, "timeto" : 1294223523 }, { "status" : "up", "timefrom" : 1294223523, "timeto" : 1294228503 }, { "status" : "down", "timefrom" : 1294228503, "timeto" : 1294228563 }, { "status" : "up", "timefrom" : 1294228563, "timeto" : 1294228623 }, { "status" : "down", "timefrom" : 1294228623, "timeto" : 1294228743 }, { "status" : "up", "timefrom" : 1294228743, "timeto" : 1294228803 }, { "status" : "down", "timefrom" : 1294228803, "timeto" : 1294228987 }, { "status" : "up", "timefrom" : 1294228987, "timeto" : 1294229047 }, { "status" : "down", "timefrom" : 1294229047, "timeto" : 1294229583 }, { "status" : "up", "timefrom" : 1294229583, "timeto" : 1294229643 }, { "status" : "down", "timefrom" : 1294229643, "timeto" : 1294230063 }, { "status" : "up", "timefrom" : 1294230063, "timeto" : 1294389243 } ] } }
Resource: Summary.performance
Method: Get Intervals of Average Response Time and Uptime During a Given Interval
Description
For a given interval in time, return a list of sub intervals with the given resolution. Useful for generating graphs. A sub interval may be a week, a day or an hour depending on the choosen resolution.
URL Syntax
/api/2.1/summary.performance/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Start time of period. Format is UNIX timestamp | Integer | no | 10 intervals earlier than to |
to | End time of period. Format is UNIX timestamp | Integer | no | current time |
resolution | Interval size | String (hour, day, week) | no | hour |
includeuptime | Include uptime information. | Boolean | no | false |
probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers. Can not be used if includeuptime is set to true. Also note that this can cause intervals to be omitted, since there may be no results from the desired probes in them. | String | no | all probes |
order | Sorting order of sub intervals. Ascending or descending. | String (asc,desc) | no | asc |
Response Attributes
Attribute | Description | Type |
---|---|---|
summary.hours.(entry).starttime | Hour interval start. Format UNIX timestamp | Integer |
summary.hours.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
summary.hours.(entry).uptime | Total uptime for this interval in seconds | Integer |
summary.hours.(entry).downtime | Total downtime for this interval in seconds | Integer |
summary.hours.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
summary.days.(entry).starttime | Day interval start. Format UNIX timestamp | Integer |
summary.days.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
summary.days.(entry).uptime | Total uptime for this interval in seconds | Integer |
summary.days.(entry).downtime | Total downtime for this interval in seconds | Integer |
summary.days.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
summary.weeks.(entry).starttime | Week interval start. Format UNIX timestamp | Integer |
summary.weeks.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
summary.weeks.(entry).uptime | Total uptime for this interval in seconds | Integer |
summary.weeks.(entry).downtime | Total downtime for this interval in seconds | Integer |
summary.weeks.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
Examples
Request
GET /api/2.1/summary.performance/85975?includeuptime=true&resolution=week
Response
{ "summary" : { "weeks" : [ { "starttime" : 1287957600, "avgresponse" : 468, "uptime" : 608400, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1288566000, "avgresponse" : 467, "uptime" : 604620, "downtime" : 180, "unmonitored" : 0 }, { "starttime" : 1289170800, "avgresponse" : 440, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1289775600, "avgresponse" : 451, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1290380400, "avgresponse" : 456, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1290985200, "avgresponse" : 465, "uptime" : 604496, "downtime" : 304, "unmonitored" : 0 }, { "starttime" : 1291590000, "avgresponse" : 489, "uptime" : 604610, "downtime" : 190, "unmonitored" : 0 }, { "starttime" : 1292194800, "avgresponse" : 466, "uptime" : 604800, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1292799600, "avgresponse" : 452, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1293404400, "avgresponse" : 447, "uptime" : 604800, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1294009200, "avgresponse" : 465, "uptime" : 382511, "downtime" : 1437, "unmonitored" : 0 } ] } }
Resource: Summary.probes
Method: Get Active Probes For A Period
Description
Get a list of probes that performed tests for a specified check during a specified period.
URL Syntax
/api/2.1/summary.probes/{checkid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
from | Start time of period. Format is UNIX timestamp | Integer | yes | |
to | End time of period. Format is UNIX timestamp | Integer | no | current time |
Response Attributes
Attribute | Description | Type |
---|---|---|
probes.(entry) | Probe identifier | Integer |
Examples
Request
GET /api/2.1/summary.probes/85975?from=1294393564&to=1294394816
Response
{ "probes" : [ 43, 42, 41, 40, 39, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 24, 23, 22, 21 ] }
Resource: Team
Method: Get Teams
Description
Returns a list of all teams.
URL Syntax
/api/2.1/teams
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
teams | A list of teams | Array |
teams.(entry).id | Team identifier | String |
teams.(entry).name | Team name | String |
teams.(entry).users | List of users in team | Array |
teams.(entry).users.(entry).id | User identifier | String |
teams.(entry).users.(entry).email | User email | String |
teams.(entry).users.(entry).name | User name | String |
Examples
Get all teams
Request
GET /api/2.1/teams
Response
{ "teams": [ { "id": "1", "name": "Team Rocket", "users": [ { "id": "1", "email": "giovanni@team-rocket.org", "name": "Giovanni" } ] }, { "id": "2", "name": "The A-Team", "users": [ { "id": "2", "email": "hannibal@ateam.org", "name": "John \"Hannibal\" Smith" }, { "id": "3", "email": "faceman@ateam.org", "name": "Templeton \"Face(man)\" Peck" } ] } ] }
Method: Get Team
Description
Returns team information.
URL Syntax
/api/2.1/teams/{teamid}
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
team | Team | Object |
team.id | Team identifier | String |
team.name | Team name | String |
team.users | List of users in team | Array |
team.users.(entry).id | User identifier | String |
team.users.(entry).email | User email | String |
team.users.(entry).name | User name | String |
Examples
Get team 1
Request
GET /api/2.1/teams/1
Response
{ "team": { "id": "1", "name": "Team Rocket", "users": [ { "id": "1", "email": "giovanni@team-rocket.org", "name": "Giovanni" } ] } }
Method: Create Team
Description
Creates a new team.
URL Syntax
/api/2.1/teams
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | yes | |
userids | Users to make team from | Comma-separated integers | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
id | Team identifier | Integer |
name | Team name | String |
users | List of users in team | Array |
users.(entry).id | User identifier | String |
users.(entry).email | User email | String |
users.(entry).name | User name | String |
Examples
Create a new team
Request
POST /api/2.1/teams
body:
name=Operations&userids=10034512,10043154
Response
{ "id": 65, "name": "Operations", "users": [ { "id": "10034512", "email": "hannibal@ateam.org", "name": "John \"Hannibal\" Smith" }, { "id": "10043154", "email": "faceman@ateam.org", "name": "Templeton \"Face(man)\" Peck" } ] }
Method: Update Team
Description
Update a team.
URL Syntax
/api/2.1/teams/{teamid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | no | |
userids | Users to make team from | Comma-separated integers | no |
Response Attributes
Attribute | Description | Type |
---|---|---|
id | Team id | Array |
name | Team name | String |
users | List of users in team | Array |
users.(entry).id | User identifier | String |
users.(entry).email | User email | String |
users.(entry).name | User name | String |
Examples
Create a new team
Request
PUT /api/2.1/teams/1234
body:
name=Operations&userids=10034512,10043154
Response
{ "id": 65, "name": "Operations", "users": [ { "id": "10034512", "email": "hannibal@ateam.org", "name": "John \"Hannibal\" Smith" }, { "id": "10043154", "email": "faceman@ateam.org", "name": "Templeton \"Face(man)\" Peck" } ] }
Resource: Teams
Method: Delete Team
Description
Remove one or more team.
URL Syntax
/api/2.1/teams/{teamid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
success | If removal succeeded or not | Boolean |
Examples
Delete teams
Request
DELETE /api/2.1/teams/1234
Response
{ "success": true }
Resource: Traceroute
Method: Make A Traceroute
Description
Perform a traceroute to a specified target from a specified Pingdom probe.
URL Syntax
/api/2.1/traceroute
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
host | Target host | String | yes | |
probeid | Probe identifier | Integer | no | A random probe |
Response Attributes
Attribute | Description | Type |
---|---|---|
traceroute.result | Traceroute output | String |
traceroute.probeid | Probe identifier | Integer |
traceroute.probedescription | Probe description | String |
Examples
Request
GET api/2.1/traceroute?host=pingdom.com&probeid=23
Response
{ "traceroute" : { "result" : "traceroute to pingdom.com (83.140.19.136), 30 hops max, 40 byte packets\n 1 67.192.120.130 (67.192.120.130) 4.803 ms 5.000 ms 5.202 ms\n 2 67.192.56.2 (67.192.56.2) 0.332 ms 0.352 ms 0.431 ms\n 3 vlan905.edge4.dfw1.rackspace.com (67.192.56.228) 0.384 ms 0.444 ms 0.497 ms\n 4 12.87.41.177 (12.87.41.177) 1.926 ms 1.983 ms *\n 5 cr1.dlstx.ip.att.net (12.122.139.122) 3.696 ms 3.725 ms 3.741 ms\n 6 dlstx01jt.ip.att.net (12.122.80.41) 1.792 ms 1.817 ms 1.840 ms\n 7 192.205.34.82 (192.205.34.82) 1.668 ms 1.828 ms 192.205.34.142 (192.205.34.142) 1.722 ms\n 8 RIX-TELECOM-AB.TenGigabitEthernet9-3.ar2.ANR3.gblx.net (64.208.169.138) 147.221 ms 146.710 ms 146.473 ms\n 9 po41-20g-r86.cr1-r85.hy-sto.se.p80.net (82.96.1.162) 146.334 ms 146.347 ms 146.776 ms\n10 83.140.54.18.cust.port80.se (83.140.54.18) 146.741 ms 146.311 ms 146.283 ms\n11 83.140.19.136 (83.140.19.136) 146.789 ms 146.710 ms 146.795 ms\n", "probeid" : 23, "probedescription" : "Dallas 4, TX" } }
Resource: Users
Method: Get list of users and contact targets
Description
Returns a list of all users and contact targets
URL Syntax
/api/2.1/users
HTTP Method
GET
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
users | A list of users | Array |
users.(entry).id | User identifier | Integer |
users.(entry).paused | If user is paused | Integer |
users.(entry).name | User name | String |
users.(entry).sms | List of SMS targets | Array |
users.(entry).email | List of EMAIL targets | Array |
Examples
Get all users
Request
GET /api/2.1/users
Response
{ "users": [ { "id": 1, "name": "User 1", "paused": "NO", "sms": [ { "id": 1, "severity": "HIGH", "country_code": "46", "number": "71234567", "provider": "nexmo" } ], "email": [ { "id": 2, "severity": "HIGH", "address": "user1@example.com" } ] }, { "id": 2, "name": "User 2", "paused": "YES", "sms": [ { "id": 4, "severity": "HIGH", "country_code": "46", "number": "709876543", "provider": "nexmo" } ] } ] }
Method: Create user
Description
Creates a new user.
URL Syntax
/api/2.1/users
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | yes |
Response Attributes
Attribute | Description | Type |
---|---|---|
user | User | Array |
Examples
Create a new user
Request
POST /api/2.1/users
body:
name=User1
Response
{ "user": { "id": 3 } }
Method: Modify User
Description
Modify a User.
URL Syntax
/api/2.1/users/{userid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
name | Name | String | yes | |
primary | Primary contact | String | no | |
paused | If user should be paused | String | no | NO |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Change name and primary status for user 3
Request
PUT /api/2.1/users/3
body:
name=Updated%20Name&primary=YES
Response
{ "message":"Modification of user was successful!" }
Method: Modify Contact Target
Description
Modify a Contact Target.
URL Syntax
/api/2.1/users/{userid}/{targetid}
HTTP Method
PUT
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
String | no | |||
number | Cellphone number, without the country code part. (Requires countrycode and provider) | String | no | |
countrycode | Cellphone country code (Requires number) | String | no | |
provider | SMS provider (Requires number and countrycode) | String | yes | NEXMO |
severitylevel | Severity level for target | String | no | HIGH |
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Change email on contact target 11 for user 3
Request
POST /api/2.1/users/3/11
body:
email=anotheresampleemail@example.com
Response
{ "message":"Modification of contact target was successful!" }
Method: Delete User
Description
Deletes a user.
URL Syntax
/api/2.1/users/{userid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Permanently delete user 1
Request
DELETE /api/2.1/users/1
Response
{ "message":"Deletion of user was successful!" }
Method: Delete contact target
Description
Deletes a contacts target.
URL Syntax
/api/2.1/users/{userid}/{targetid}
HTTP Method
DELETE
Successful HTTP Response
200
Parameters
None
Parameter name | Description | Type | Mandatory | Default |
---|
Response Attributes
Attribute | Description | Type |
---|---|---|
message | Message | String |
Examples
Permanently delete contact target 2 for user 1
Request
DELETE /api/2.1/users
Response
{ "message":"Deletion of contact target successful" }
Resource: User
Method: Create a new contact target
Description
Creates a new contact target.
URL Syntax
/api/2.1/users/{userid}
HTTP Method
POST
Successful HTTP Response
200
Parameters
Parameter name | Description | Type | Mandatory | Default |
---|---|---|---|---|
String | no | |||
number | Cellphone number, without the country code part. (Requires countrycode) | String | no | |
countrycode | Cellphone country code (Requires number) | String | no | |
provider | SMS provider (Requires number and countrycode) | String | no | NEXMO |
severitylevel | Severity level for target | String | no | HIGH |
Response Attributes
Attribute | Description | Type |
---|---|---|
contact_target | Contact Target | Array |
Examples
Create a contact target for user 3
Request
POST /api/2.1/users/3
body:
email=example1@example.com&number=0701234567&countrycode=46&provider=nexmo&severitylevel=high
Response
{ "contact_target": { "id": 11 } }