API FAQ

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

 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.

 Also see our API Code Examples section.

How to Indicate List Id in Ongage API Calls

There are a few ways to indicate which List ID you want to address when issuing an Ongage API call.
Since that's the case, a precedence is required. Following is the list_id precedence in order from the highest to lowest precedence:

1. In the request body: POST api/mailings { "list_id" : 1111 }
2. In the query param: https://api.ongage.net/api/mailings/?list_id=1111
3. In the URL route param: https://api.ongage.net/<list_id>/api/
4. The system will use the account's default list ID, when no list id is indicated at all!

For example:

1. If a user has indicated List IDs at all 3 possible places as shared in the example below, then in this case list_id=3333 will be the one that applies.
   POST 1111/api/mailings?list_id=2222 { "list_id" : 3333 }
2. Between query param and route param, List ID indicated as query param takes higher precedence. So, if the List IDs are indicated as below, then the system will use list_id = 2222.
   POST 11111/api/mailings?list_id=2222
3. Having said that, it is best practice to use the list_id in just one place, to reduce human error.

 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.

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

• Create/Add a new contact (email address) to a list.
• You can use this command to also add multiple new contacts.
  Note: This method also has has an 'overwrite' option, so that it could be used both for add/create and update.

PUT /api/v2/contacts

• Update existing contacts in the list based on list_id and email address or contact id.

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

• How many you can add/update in one synchronous call depends on how much data you're posting.
• Typically you can update anywhere between 5-50 contacts in one command.
• If you're posting very little data you might even be able to get up to to 100.
•  But for large numbers of Add/Update see the following section about the import command.

How to Issue an Import via the API 

• For adding/updating large amounts of contacts aka bulk import, use this class of API methods: Import API Methods.
• This is the same CSV import as appears in the UI. This API, enables users to automate imports, rather than upload them manually.
• When adding/updating more than a hundred contacts, and particularly when adding/updating big volumes list data fields, or if you're doing a daily or nightly batch update of your Ongage list, use the POST /api/import command – instead of the of the contacts methods above.

How to Issue a Transactional Email or SMS via the API

• Transactional messages (email or SMS) can be issued using the following API method: POST /api/transactional/send
• Typical scenarios for transactional emails are welcome emails upon registering or a receipt following a purchase transaction. 
  •  To be noted that welcome emails don't have to be API coded, as Ongage offers an automatic built-in welcome email feature, that can be setup from the List Settings Page (see there help section on "How to Setup a List Welcome Email").
• Each List comes with 1 default transactional campaign already setup, but you can add additional campaigns for different types of transactional emails with the following method: 
  POST api/transactional which is used to create a new transactional mailing campaign.
• If you don't indicate a mailing_id when calling the transactional mailing method, then all mailing stats and data will get associated with the default transactional campaign for that list.
• By default when issuing a call to send a transactional message, the contact's status (unsub, bounce, complant status) is ignored, that's in order to accommodate sending receipts regardless if the contact is unsubscribed or not (similarly suppression lists are also ignored). The Transactional method does have flags to indicate whether to take into account the status and/or suppression list . See details about the check_status flag and check_global_and_list_suppression flag under the API method: POST /api/transactional/send
• When issuing a Transactional message you can either indicate the Email/SMS Message ID or Send HTML/Text  Content in the body of API Call. In the latter case you will need to encode the HTML code passed in the body of the call by using some function like: json_encode($html-email); (See example here: POST /api/notify_transactions).

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

• All of campaign/aggregated analytics reports that you see in the Ongage UI (User Interface), behind the scenes use the Ongage  API reporting method: POST /api/reports/query
  
  

How can I retrieve the Ongage Contact Activity Report

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

• See the class of methods found here: Class Contact_Activity starting with POST api/contact_activity to issue the report.
• For more about this report in general see Contact Activity Report in the Analytics online help section.

How to retrieve all transactional campaigns for a given list

• GET api/mailings?mailing_type=transactional&list_id=1111
• Where list_id is the number of the list you're querying about
• See: https://ongage.atlassian.net/wiki/spaces/HELP/pages/939458561/Campaign+Mailing+API+Methods

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

How to do a List Search with the API

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. The API limit for you account, you can find in your Account → Profile Page, under the 'Account Limits' section of the page see: 'Maximum number of API calls allowed per minute'
   
   
   
   1. If you issue more API calls beyond your account 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"
    }
}

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.

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

Appendix

API Exception response sample 

• error: true - means the API call failed.
• error: false - means the API call succeeded.

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