OnPage REST API
OnPage REST API allows:
- Send OnPage Messages to individuals and groups
- Send OnPage Messages in different priorities: High or Low priority
- Send OnPage Messages with attachments
- Receive message audit trails via callbacks
OnPage REST API uses JSON format in all requests and responses.
To use the QA environment use https://qaapi.onpage.com/v1 and https://api.onpage.com/v1 for the production environment.
For callbacks web documentation use https://api.onpage.com/v1/callback and for Sending messages use https://api.onpage.com/doc/?url=/v1/swagger#/Authentication.
Each response uses an HTTP status code to inform if request was proceeded successful or with an error.
|HTTP Status Code||Description|
|400||Wrong request format|
|401||Unauthorized. Access is denied due to invalid credentials.|
|403||Unauthorized. Account is not active.|
|412||Invalid input. No active recipients found.|
|450||Token is expired.|
|500||Internal server error.|
Token and Permissions
Every request to the OnPage REST API has to be authenticated and have the correct permissions to execute the requested operation. The OnPage REST API uses a TOKEN to achieve this. A token can be generated in different ways:
- Automatically by the OnPage REST API request from the customer side.
- By OnPage Support Team.
The token has an expiration date and time. If a request is made and the token has expired the task will not be processed by the OnPage server. Currently, the TOKEN can be requested from the customer application and will expire after 24 hours.
To obtain a TOKEN you must have the following Enterprise credentials:
- Enterprise user name
- Enterprise password
To request your credentials please contact OnPage Support (http://onpage.com/contact-support/).
Once the token is obtained it has to be included in the token key of all requests to the OnPage REST API.
Note: It is not necessary to request a token every time you send a message. A token can be reused until it expires after 24 hours.
To send an OnPage message with an attachment you must upload the attachment first. The server response contains the attachment ID that can be used in the array of assigned attachments in the Send Page API request.
Note: the attachment upload API URL is different from the basic REST API URL schema. Use the following URL addressees:
For QA: https://qanps.onpage.com/onpage-gateway/rest/attachment (POST)
For Production: https://nps.onpage.com/onpage-gateway/rest/attachment (POST)
|Recipients||ARRAY OF STRINGS||Yes||Array of OnPage ID for groups or individual recipients|
|Priority||“HIGH” or “LOW”||Yes||Message priority|
|Attachments||ARRAY OF IDs||No||Array of uploaded attachment IDs|
|callbackUri||STRING||No||URL for delivery confirmations to be sent to|
“from”: “OnPage API”
If the recipient’s field in the request contains non-existing recipients they will be returned in the nonExistingRecipients array in the response. Note: Any recipients that are in the nonExistingRecipient array will not receive the OnPage message.
The messageId field contains the OnPage REST API message ID that should be stored in order to trace status updates returned in callbacks (if needed and requested).
Status updates for sent messages can be obtained in callbacks to the URL address specified in the callbackUri field of the Send Message request. The callback service has to process both GET and POST requests on the same URL address.
GET Request is needed to initiate the callback. A user name and password is specified for callbacks and are determined by the user. The level of security of the user name and password is up to the user. If the fields match, a response token is returned. The token is required in the post request.
Credentials will be transferred in body in JSON format with keys user and password.
The response has to contain the TOKEN that is used in the next POST request.
Status updates will be sent in a POST request to the customer callback service. The token will be transferred in the body JSON with token key.
|messageId||STRING||Yes||OnPage message ID|
|status.id||OBJECT||Yes||OnPage status ID|
|Yes||Status update type|
|status.timeStamp||STRING DATE||Yes||Timestamp of status update in UTC|
Sample of a callback request from the OnPage Server to customer callback service:
timeStamp: ’11/26/2015 10:06:04′
The customer callback service must return a response similar to the response of the OnPage REST API server. In case of success HTTP status code has to be 200.