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.


Service URL Addressees

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.

Error Codes

Each response uses an HTTP status code to inform if request was proceeded successful or with an error.

HTTP Status Code Description
200 Success
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:

  1. Automatically by the OnPage REST API request from the customer side.
  2. 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:

  1. Enterprise user name
  2. 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.

Getting Token from REST API



https://SERVICE-URL/authenticate (POST)


“user”: “helloworld”,
“password”: “ghf3j3d5d37k824234234”






  “permissions”: [






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.

Upload Attachment

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)



“success”: true,


Send Message

JSON fields:

Field Name Type Required Description
Subject STRING Yes Message subject
Body STRING No Message body
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


https://qanps.onpage.com/onpage-gateway/rest/page (POST)




 “message” {
“subject”: “PAGE from new REST API with Attachment”,
“body”: “some body value”,

  “from”: “OnPage API”
“attachments” : [1239478364834934739434]

  “callbackUri”: “




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).

“nonExistingRecipients”: [],
“messageId”: “a23bfa0863a8a1bb1abcee18cf004ffdc97aca4ddcffcac1f97672ade7783161”



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.

“user”: “helloworld”,
“password”: “ghf3j3d5d37k824234234”


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.

JSON fields:

Field Name Type Required Description
messageId STRING Yes OnPage message ID
status.id OBJECT Yes OnPage status ID
status.value “PENDING”







Yes Status update type
Status.replyText STRING No Reply text
status.timeStamp STRING DATE Yes Timestamp of status update in UTC


Sample of a callback request from the OnPage Server to customer callback service:



status: {

messageId: ‘ca33ba530e311909bd131c1e3db86290082daac62770a7bcc934fc19fc647df1’,

id: ‘e5effcf913f728e1b7b056bee80a4d3d8e0803a516b36303afa3fe05d4542d43’,

value: ‘Sent’,

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.