onpage logo

Getting Started

OnPage REST API uses JSON format in all requests and responses.

This page will help you know the steps to integrate with OnPage’s functionality.

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

For sending messages, use https://api.onpage.com/doc/?url=/v1/swagger#/Authentication.

Error Codes

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

HTTP Status CodeDescription
400Wrong request format
401Unauthorized. Access is denied due to invalid credentials.
403Unauthorized. Account is not active.
412Invalid input. No active recipients found.
450Token is expired.
500Internal 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 the 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.

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 addresses:

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 NameTypeRequiredDescription
SubjectSTRINGYesMessage subject
BodySTRINGNoMessage body
RecipientsARRAY OF STRINGSYesArray of OnPage ID for groups or individual recipients
Priority“HIGH” or “LOW”YesMessage priority
AttachmentsARRAY OF IDsNoArray of uploaded attachment IDs
callbackUriSTRINGNoURL 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 requests are needed to initiate the callback. A username and password is specified for callbacks and are determined by the user. The level of security of the username 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 NameTypeRequiredDescription
messageIdSTRINGYesOnPage message ID
status.idOBJECTYesOnPage status ID







YesStatus update type
Status.replyTextSTRINGNoReply text
status.timeStampSTRING DATEYesTimestamp 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, the HTTP status code has to be 200.