Partners Support Log In
Frank Hagan


    Back to Top

    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 Interactive documentation to test your API code is at

    This article will show how to use the interactive documentation, and is intended for those familiar with API programming.

    Getting Started

    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:

    API Key Listing

    If there are no API keys listed:

    1. Click the New API Key button

      new API key button
    2. 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.

      Define new API key
    3. Save the API key. Copy the API Key and APP ID for use in the interactive API documentation.

    Navigate to 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.

    top of API doc listing - standard objects

    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.

    all api endpoints

    Opening the Contacts section shows the actions available.

    contacts listing in new api doc

    Clicking on /Contacts/saveorupdate loads the endpoint and all the fields available in a Contact Record, including custom fields and fields from Custom Objects.

    endpoint details

    Multi Option fields show the choices available by option number:

    multi-option fields

    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.

    Using criteria with the API

    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

    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!

    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

    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. and

    Articles in this section

    Created - Updated
    Have more questions? Submit a request