Using the New API
Applies to: All ONTRAPORT accounts.
The new API from ONTRAPORT exposes many more endpoints. The documentation for our API is at https://api.ontraport.com/doc. Interactive documentation to test your API code is at https://api.ontraport.com/live.
This article will show how to use the interactive documentation, and is intended for those familiar with API programming.
Obtain an APP ID and API Key from an active ONTRAPORT account in Administration > ONTRAPORT API Instructions and Key Manager. You can use any API Key and APP ID pair shown in the listing:
If there are no API keys listed:
- Click the New API Key button
- Name the API key and select the Admin / Account Owner user in the drop down box. You do not need to select any other permissions for the new API.
- Save the API key. Copy the API Key and APP ID for use in the interactive API documentation.
Navigate to https://api.ontraport.com/live/ and enter the API Key and APP ID into the boxes at the top right. If connection is sucessful, the API Key and APP ID field will be outlined in green. All of the endpoints available for the connected account will be loaded into the doc.
Using the Interactive API Doc
Every account will display the default API endpoints, objects, tasks, messages, forms, landing pages and transactions at the top of the page. Note the current rate limiting "requests per minute" and a link to this article are also provided.
Below that top section every endpoint available in the account is listed. This will vary by account due to optional items such as Custom Objects. In the following image, Animals, Bids, Businesses, Children and Companies, highlighted in yellow for illustration purposes, are all Custom Objects in this particular account.
Opening the Contacts section shows the actions available.
Clicking on /Contacts/saveorupdate loads the endpoint and all the fields available in a Contact Record, including custom fields and fields from Custom Objects.
Multi Option fields show the choices available by option number:
Note: ONTRAPORT uses the email field as a unique, indexed field. We strongly recommend using the API call shown, /Contacts/saveorupdate, and pass it the email address with your update. This will search for a matching Contact Record and add the information to it, or create a new Contact Record if that email does not exist. This avoids having to query the API to see if the email exists first.
At the very bottom of the API doc listing is the Criteria section, showing how to pass criteria to limit the amount of data returned from any API call.
Obtaining Support for the New API
While we can't teach you how to program using our API, our QA and developers are happy to assist any programmers who run into a problem with a specific API call. Please prepare a plain text document with the code, the error message you are receiving, and the API Key and APP ID for the account. Attach the text file to an email with your contact information and email it to firstname.lastname@example.org.
Usecases (Code Samples)
This section of our API documentation contains a number of useful multistep processes which can be completed via the API. Explanations of the steps involved are given, and complete code samples are included. The example PHP scripts are written using our official PHP client library. The initial usecases include:
- Change gateways on an open order
- Completed task outcomes/followup
- Create and assign a task
- Create transaction offers
- Get all Contacts with a tag
- Log a transaction
- Product-specific coupons
- Sales reporting
- Search message subject
- Tracked links in messages
Q. Will this affect the API that I already developed?
A. No! The prior API will continue to work as before.
Q. Do you have complete code examples for the new API?
A. No, but the interactive API application has some code examples built in.
Q. Does ONTRAPORT limit the number of calls you can make?
A. Yes, the current limit is 180 requests per minute. This is a rolling limit that resets each minute.
Q. Which version of the API should I be using?
A. We recommend you use the new API.
Q. Where can I submit feedback and feature requests for the API?
A. Send them to email@example.com!
Q. How do I contact API support?
A. Send your code in a text file, attached to an email with your contact information and explaining the issue you are having, including error messages, to firstname.lastname@example.org.
Q. How stable is your API? How often are API changes made that can break my code?
A. Our API is very stable and we monitor it regularly. If updates are made, we make every effort to ensure our updates will not break other integrations.
Q. How can I be advised of any changes to the API?
A. Subscribe to the API RSS Feed!
Q. What are your API's originating IP addresses?
A. 126.96.36.199/27 and 188.8.131.52/27