Public API Documentation
Our public API is simple and easy to use.
These are the calls available:
| URL | HTTP Method | Description |
| https://www.notifymyandroid.com/publicapi/verify | GET | Verifies if an API key is valid. |
| https://www.notifymyandroid.com/publicapi/notify | POST | Sends a notification. |
Note that we strongly encourage the use of HTTPS on all your API calls, although you can fallback to HTTP in case you have no other choice.
When you call one of the APIs above, you will receive a xml formatted answer. You can find the details of a success and error messages below.
API Calls
/publicapi/verify
This call accepts a single API key as a parameter and returns if that key is valid or not.
Recommended HTTP Method: GET
All data submitted should be UTF-8 encoded.
| Parameter | Length (bytes) | Description |
| apikey | 48 | The api key that you want to test if it is valid. |
| developerkey (optional) |
48 | Your developer key, if you have one. This is optional. |
Return codes:
| Code | Description |
| 200 | The 'apikey' supplied is valid. |
| 400 | The data supplied is in the wrong format, invalid length or null. |
| 401 | The 'apikey' provided is not valid. |
| 402 | Maximum number of API calls per hour exceeded. |
| 500 | Internal server error. Please contact our support if the problem persists. |
Please see the return message format for more details.
/publicapi/notify
This call sends a notification. Note that you can pass an unlimited number of API keys on a single call.
Recommended HTTP Method: POST
All data submitted should be UTF-8 encoded. All fields are required, unless noted.
| Parameter | Length (bytes) | Description |
| apikey | unlimited | API keys separated by commas. Each API key is a 48 bytes hexadecimal string. When using multiple keys, you will only get a failure respose if all of them are not valid. |
| application | 256(max) | The name of the application that is generating the call. Example: Nagios |
| event | 1000(max) | The event that is been notified. Depending on your application, it can be a subject or a brief description. Example: Service is down! |
| description | 10000(max) | The notification text. Depending on your application, it can be a body of the message or a full description. Example: Server: 1.2.3.4 Service: mysqld Status: DOWN Time of the alert: 1/21/2011 1:32am |
| priority (optional) |
- | A priority level for this notification. This is optional and in the future will be used to change the way NMA alerts you. Possible values: -2, -1, 0, 1, 2 -2 = Very Low -1 = Moderate 0 = Normal 1 = High 2 = Emergency |
| developerkey (optional) |
48 | Your developer key, if you have one. This is optional. |
| url (optional) |
2000(max) | An URL/URI can be attached to your notification. You can send URL's or URI's supported by your device. The user will be able to long-click the notification and choose to follow the attached URL/URI, launching the application that can handle it. |
| content-type (optional) |
Limited Options | You can set this parameter to "text/html" while sending the notification, and the basic html tags below will be interpreted and rendered while displaying the notification:
|
Return codes:
| Code | Description |
| 200 | Notification submitted. |
| 400 | The data supplied is in the wrong format, invalid length or null. |
| 401 | None of the API keys provided were valid. |
| 402 | Maximum number of API calls per hour exceeded. |
| 500 | Internal server error. Please contact our support if the problem persists. |
Please see the return message format for more details.
Return message format
Always use a XML parser. We should release changes and improvements over time that will change attributes and messages that may brake direct string parsers.
All messages will return a HTTP status code 200. That way you know when you were able to contact the server and the error is an application error or something else.
Error message
The error message contains an ERRORCODE and an ERRORMESSAGE. The ERRORMESSAGE is usually a more detailed message, like which parameter is invalid.
<?xml version="1.0" encoding="UTF-8"?> <nma> <error code="ERRORCODE">ERRORMESSAGE</error> </nma>
If the error is a 402 (API calls per hour limit exceeded) you will receive an extra attribute resettimer=TIMELEFT, which is a number that represents the minutes left before your limit per hour resets.
<?xml version="1.0" encoding="UTF-8"?> <nma> <error code="402" resettimer="TIMELEFT">Your IP exceeded the maximum number of API calls per hour allowed.</error> </nma>
Success message
The success message always contains a code 200 with two extra attributes: CALLSREMAINING and TIMELEFT. CALLSREMAINING is the number of API calls you have left before it resets. TIMELEFT is the number of minutes till the reset.
<?xml version="1.0" encoding="UTF-8"?> <nma> <success code="200" remaining="CALLSREMAINING" resettimer="TIMELEFT" /> </nma>
Note that the 'remaining' attribute can return negative in case you are using a developer key that bypasses your hourly limit. We designed it that way so the developer can keep track if they are exceeding the usual quota.