Table of Contents:

API quick start

Want to get started with the Ongage API? Here's where to start! 

  1. This FAQ!! (First and foremost).
  2. The API Guide: which contains a general intro, overview and is the parent section to all available API methods.

How do I know if my account has API Access

  1. Go to the Account Profile page (only Admins have access to this page).
  2. See there the line item: # of API Calls.
    1. If you're account does not have API access, then under the column Current limit it will say Disabled.
    2. If you're account does have access, then then under the column Current limit it will say the number of API calls per minute allowed in your account.

API Authentication Credentials

  1. In order to connect to your Ongage account via the API, you'll need the Username and Password of the Ongage User who will be using and issuing the API commands, along with your Account Code, that you can find under the Account Profile page: 

    (warning) Note: the Account Code is a unique alphanumeric string and is not the numeric Account ID

  2. These are the credentials you'll need to send in the request header:

    X_USERNAME: your_ongage_username
    X_PASSWORD: your_ongage_password
    X_ACCOUNT_CODE: your_ongage_account_code

(info) It is recommended that the API User be either an Admin or General User. For a list of user types see the User Management help guide.

(info) Also see our API Code Examples section.

How to Indicate List Id in Ongage API Calls

There are a variety of ways to indicate which List ID you want to address when issuing an Onage API call.
Since there are several ways to indicate the list_id in an API command, a precedence is required.
Following please find the list_id indication precedence:

  1. In the request body: POST api/mailings { "list_id" : 1111 }
  2. In the query param: api/mailings?list_id=1111
  3. In the URL route param: 1111/api/mailings
  4. Use the account's default list ID when no list id is indicated at all!

(warning) Note the precedence means that if a user will issue a call with List IDs indicated, as in the following example:
Then, the system will use list_id=2222, because the query param takes precedence over route param.
Having said that, it is best practice to use the list_id in just one place, to reduce human error.

(info) As is the case everywhere in the Ongage platform, when no List ID is indicated, then the default List ID for that account is the one that is used.

How to Add and Update Contacts to a List

To add contacts to a list or update contacts in a list use the class of methods here: Class Controller_API_Contacts

The following commands can typically be used behind your web-form on your website for adding / updating new / existing contacts to your Ongage list or from your CRM:

POST /api/v2/contacts

PUT /api/v2/contacts

(info) Both methods support adding or updating more than one contact at a time.

How to Issue an Import via the API 

How to Issue a Transactional Email or SMS via the API

How can I retrieve aggregated campaign stats from Ongage into our CRM / Data Warehouse

How can I retrieve the Ongage Contact Activity Report

Typically used for DB sync between Ongage and back-end CRM / Data Warehouses 

How to retrieve all transactional campaigns for a given list

How to Unsubscribe (and/or Change Status) of a Contact in your List via the API

If you want to unsubscribe a contact (email address) via the API, here's what you need to do:

  1. Use the the following API List Contact method to do this update: POST /api/v2/contacts/change_status
  2. If you also want to associate the unsubscribe with the corresponding CID (campaign id) that the unsubscribed occurred on, you will need to pass the optional ocx_child_id. This is the sub-campaign of the parent campaign (each chunk get's its own sub-campaign id). In order to get the correct ocx_child_id, you will need to pass that in the link of your email.

(question) Note: You can also use this method to "resubscribe" / "unsubscribe" / "remove" / "bounce" / "complaint" / "soft_bounce" – as described in the link above.

How to do a List Search with the API

There are 2 methods that can be used:

  1. GET /api/contacts/by_email/<email address> is a synchronous search using the email address field only (which is the key field and indexed field of the Ongage list).
  2. POST /api/contact_search is an asynchronous search and should be used whenever you're searching your list, using a field other than the email field. E.g., search all list members where gender is female.

Account Level API Methods

AKA Across all lists

  1. Account level contact lookup - see: GET /api/contacts/cross_account? Searches for a given email in all lists, that the API user doing the search, has access permissions to. Retrieves all data fields and status of that contact in each of the lists that it appears in. Using the optional behavior parameter you can also retrieve Open, Click and Sent stats for that email.
  2. Get stats from all lists in an account - see: POST /api/reports/query and note: "list_ids": "all". See sample JSON below.

How many API calls can I issue per minute

  1. The default limit is 300 API calls every 60 seconds (i.e., 300 API calls per minute). This limit can be increased (even by a lot), based on your Ongage package. Please consult Ongage support for more information on this matter.
    1. If you issue more API calls beyond the limit, you will get a denied response with HTTP 429 error (see below).
    2. This is done in order to ensure stable and continuous API service.
    3. Therefore in your code you should have a built-in retry and back-off mechanism, in order to manage that rate, so even if you breach the limit and get denied, you can resend it according to the allowed rate.
    4. Suggested exponential back-off: 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes.
  2. Moreover, you can have no more than 10 API calls running in parallel at any given time.

HTTP Error Code 429

See previous section right above this, for the context regarding this error message. Here is what the HTTP 429 error code looks like:

    "metadata": {
        "error": true
    "payload": {
        "code": 429,
        "errors": [],
        "message": "Calls per minute exceeded"


How to Handle HTTP 5xx Error Codes

Use a Retry Mechanism In Order to Handle HTTP 500 / 503 / 504 Error Codes

This could happen if the Ongage API server has temporarily/momentarily maxed out of capacity. By and large this is a rare error code to run into. In such cases Ongage recommends the following:

  1. Your API scripts should be set to retry the request after 60 seconds in case you run into any 500 error code.
  2. Moreover, your script should employ an exponential back-off, so if after 1 minute you still get some 500 error code, then wait 2 minutes, 4 minutes, 8 minutes, 16 minutes.

(info) For a list of all HTTP Error Codes see the Appendix at the bottom of this API Guide


API Exception response sample 

  "metadata": {
	"error": true,
	"type": "http"
  "links": [],
  "payload": {
	"message": "Please insert a valid Email address",
	"code": 400