Table of Contents:
The Ongage API
Before starting here, please visit our API FAQ for all basics and getting started questions.
- The Ongage UI is written completely on top of the Ongage API! Meaning anything you can do in the UI you can do with the API and more!
- The Ongage API is a modern full-featured JSON REST API.
Here are some online resources about REST:
- Representational state transfer
- Using HTTP Methods for RESTful Services
No SDK is required in order to use the Ongage API all you need is:
- An Ongage account.
- API User Login credentials and account code (see API FAQ).
- The desired API method described in the subsection of this document.
About API Access and Access Permission Denied HTTP 403
Note: your account needs to be allowed to have API access. See our pricing page to see if your plan includes API access or ask your account manager. If you don't have API access you will get an HTTP 403 permission denied response.
The Ongage API Endpoint
The API endpoint URL is: https://api.ongage.net/api/<followed by the requested entity>
Overview of Key API Controllers
The Ongage API is organized into the following key controllers:
- Campaign: contains all the API methods related to creating emails, campaigns as well as sending transactional messages.
- ESP: has the get method for retrieving info on your current ESP connections.
- List: contains all the methods required to add, update, delete, unsubscribe, import and export contacts from your Ongage Lists.
- Report: contains the query report method which you can use to create and extract any type of aggregated analytic report that you'd like. This is the method used behind many of the analytics screens in Ongage.
All API Methods Organized in Subsection Pages
API Error Codes
HTTP Error Codes
- 400 Bad Request (usually invalid JSON provided).
- 401 Unauthorized (Please check your Username/Password/Account Code).
- 403 Forbidden (permission denied, check if you account is allowed to issue API calls, check if the API user you are using is authorized for API, is at least a General User, and has access to the list they're trying to access).
- 404 Not Found (check your URL for any typo and/or make sure the end-point is correct).
- 408 Request timeout
- 412 Precondition Failed (this HTTP code is used for ALL validation errors in the API).
- 429 Too Many Requests (you're making more than your allotted number of API calls per minute. See Misc. Technical Specs).
- 500 Internal Server Error (something has gone wrong on the API server).
- 503 Service Unavailable (Ongage API might be in maintenance/temporary overloading and is unable to handle any request).
- 504 Gateway Timeout (probably the API server failed to retrieve all the requested information from another server in a timely fashion, therefore, the call has failed).
Empty Object Fields
Empty Object Fields Return as Empty Arrays
Note: every object field in the API, will return an empty array when empty, and not an empty object.
Do API calls take into account the time zone of the Ongage user issuing the API call
- Yes when a user supplies a date format and not Unix time-stamp. If a Unix time-stamp is supplied in API call, then the time-zone adjustment is not performed.
- Having said that we recommend using Unix time-stamp when using the API.
- When you issues a call to an API method that includes a date and/or date time-stamp (e.g., dd/mm/yyyy hh24:mi) that is not a Unix time-stamp (e.g., 1491748377), the API will automatically reconfigure those to the time-zone setting of the API user.
- So for example, in the following sample JSON the analytics report will be based on the day according to the time zone of the user who issued this API call: https://ongage.atlassian.net/wiki/spaces/HELP/pages/868057089/Report+API+Method
Json Formatters and Validators