search
Partners Support Log In
Solutions
Ontraport’s solutions work together to give you everything you need to run your business in one centralized, easy-to-use platform.
Check Out Pricing
Give each customer a tailored experience to drive sales while eliminating busy work for your team.
Send emails that keep your customers engaged so your sales continue to grow with your list.
Land more leads and customers with web pages that promote your products and show off your brand.
Use visual analytics to make confident decisions for smarter marketing and more profits.
Create a custom subscription site and manage it from one place to earn recurring revenue with ease.
Optimize your entire sales process to generate more prospects, nurture your leads, and close more sales.
Online sales to seamlessly manage payments and subscriptions.
Personalize every customer interaction to generate more sales using all-inclusive customer data.
Automate your team’s most time-consuming, repetitive tasks to create more freedom in your business.
Drive and track revenue generated by referral partners who receive commissions for helping you grow.
Solutions
Resources
Find free content on the latest marketing strategies, using Ontraport in your business, and finding the right software solutions.
Visit the Blog
Marketing Strategies
Browse a collection of articles on marketing automation, email marketing, CRM, membership sites and more.
Implement proven marketing processes with our easy-to-follow worksheets and checklists
Download our best-practice guides, complete with data-driven insights and tactics to help you optimize your marketing.
Listen in as Ontraport CEO Landon Ray talks with with a star-studded cast of entrepreneurs, marketers and thought leaders.
Learn everything you need to know to develop fundamental marketing strategies with our digital handbooks.
Using Ontraport in Your Business
See if Ontraport is the right fit for you — compare the top marketing automation and CRM software on the market.
See exactly what you can do with Ontraport, and learn how you can personalize it to perform your specific needs.
View the most frequently asked questions about Ontraport so you can get clarity and feel confident in your buying decision.
Take a guided tour through the five phases of the customer lifecycle in a simulated business powered by Ontraport.
Get an honest estimate of the return you can expect from an investment in Ontraport's software.
Resources
Customers
Ontraport empowers businesses large and small, all over the globe, and in every industry, to succeed.
Read the Reviews
Hear From Our Customers
Don’t just take our word for it. See why businesses from every industry love Ontraport’s marketing automation and CRM software.
Find out how our users have created thriving businesses and transformed their lives with Ontraport.
Industries We Serve
Personal Services
Professional Services
Online Retail
Coaches & Speakers
Author & Bloggers
Brick & Mortal Retail
Technology
Manufacture & Wholesale
Your Unique Business
Your Unique Business
Customers
Chat With Us chat
Start Free Trial
menu
close
Why
Ontraport?
Solutions keyboard_arrow_down keyboard_arrow_up
Marketing Automation
CRM
Email Marketing
Landing Pages
Marketing Analytics
Sales Force Automation
Ecommerce
Business Process Automation
Membership Sites
Referral Programs
Resources keyboard_arrow_down keyboard_arrow_up
Ontraport Blog
Step-by-Step Templates
In-Depth Guides
Modern Ontrapreneur Podcast
Marketing Blueprints
Software Comparisons
Feature Use Cases
Get the Facts
Exploring Ontraport
Calculate Your ROI
Customers keyboard_arrow_down keyboard_arrow_up
Customer Reviews
Success Stories
Support Center
Partner With Ontraport
Chat With Us chat
Check Out Pricing
Martin Cogburn
Updated

Contents

    Back to Top

    Contacts API (deprecated)

    About the Contacts API

    Applies to: ONTRAPORT Plus and above.

    Note: We have a new and improved API for ONTRAPORT users. You can find the documentation HERE. The old API code found here previously is now deprecated.

    For the examples below, we've added the equivalent calls using the new API (where available). While we don't have any plans to disable the old API, we do suggest switching over to this faster, more powerful version. Please note that with the new API, authentication is handled via the request headers (as opposed to being passed in the POST data). Please refer to the documentation page for more information.

    Contacts API

    All of our example code can be found on GitHub

    Table of Contents

    1. Add - Add a contact
    2. Update - Update a contact
    3. Fetch - Pull contact record for a specific contact
    4. Delete - Delete a contact
    5. Key - View a template of a contact record
    6. Add Section - Add a new field section
    7. Edit Section - Edit an existing field section
    8. Remove Section - Remove a field section
    9. Remove Field - Remove a single field
    10. Add Dropdown - Add a dropdown field
    11. Remove Dropdown - Remove a dropdown field
    12. Search - Search for contacts matching a given criteria
    13. Pull Tag - Pull a list of tags with corresponding IDs
    14. Fetch Tag - Pull a list of tags
    15. Fetch Sequences - Pulls a list of sequences with corresponding IDs
    16. Add Notes - Add notes to a contact(s)
    17. Fetch Notes - Return notes for a contact(s)
    18. Add Tag - Add a tag(s) to a contact(s)
    19. Remove Tag - Remove a tag(s) from a contact(s)

    Frequently Asked Questions

    Introduction

    The contacts API allows for adding, deleting and modifying contacts within the ONTRAPORT account. In order to use the Contacts API, you must submit a standard HTTP (Hypertext Transfer Protocol) POST request to the ONTRAPORT contacts API server.

    Authentication

    Use of the Contacts API requires an API App ID and API Key. These can be generated within your ONTRAPORT account by going to Account > API Instructions and Key Manager.

    Also, be sure to select the appropriate permissions for the key you are about to generate (for example, if a key does not have "add" permissions selected, it will not be able to be used to add type requests.

    Note that if you have not done so already, you will need to submit a request for access to the API. Once access is granted, you can generate as many API App ID/API Key combinations as you want. For more information on how to generate a key or how to request access, please contact customer support.

    Requests Overview

    Currently we use REST Requests to handle requests to the web server. Typically XML (or JSON for add, update and search requests) data is posted via POST to the feed URL and a 'success', 'failure' or 'return data' will be returned depending on the type of call. REST supports a number of web server environments for development, and it's a pretty easy system to learn. Learn all about REST.

    A typical request consists of two parts; a URL and post data.

    The post URL is comprised of the API address (in this case, https://api.ontraport.com/cdata.php) along with the following paramenters.

    Parameter Data Description
    Appid string (Required) You must first generate an App ID to use the API. Instructions to generate a key are in the "Authentication" section (above).
    Key string (Required) This is a unique key that you can generate for use in your App ID.
    reqType string (Required) Request type. See "Request Types" (below) for information detailing each request type.
    data string (Required in all but key requests) XML or JSON data (type and contents varies based on request type)
    f_add boolean When set, forces a new contact to be added (regardless if a contact with a matching email address is found).
    Note: "Add" requests initialize this to true, "update" requests initialize it to false
    return_id numeric

    1 - full contact record(s) is/are returned in addition to the standard Success/Failure message

    2 - returns the contact ID and date last modified for the contact(s) in addition to standard Success/Failure message
    count boolean For search types, returns the number of contacts who matched the search criteria.
    getIds boolean For search types, returns the contact IDs of contacts who matched the search criteria. Note that this is overridden if "count" is set. If both getIds and count are set, only the number of matching contacts will be returned.

    A basic request should resemble the following:

    Request URL:
    https://api.ontraport.com/cdata.php

    POST data:
    appid=abc12345&key=xyz54321&reqType=add&return_id=1&data=[data string]

    In addition to the URL, most requests (all but the "key" request) require some data be passed. This can be as little as a contact ID (in the case of a "delete" request) or as much as all of the fields with their respective values (in an "add" or "update" request).

    The basic structure is as follows:

    <contact>
//Separate field sections are enclosed in "Group_Tag" elements
<Group_Tag name="Contact Information">
//Separate fields are enclosed in "field" elements
<field name="First Name">Tim</field>
<field name="Last Name">Lincecum</field>
<field name="Email">t.lincecum@test.com</field>
</Group_Tag>
<Group_Tag name="Sequences and Tags">
<field name="Contact Tags">Test</field>
<field name="Sequences">*/*3*/*8*/*</field>
</Group_Tag>
</contact>

    Date Format

    All dates passed to the ONTRAPORT API must be in Unix Time format (also known as seconds since epoch). To get the Unix Time version of a standard date/time, you can use a converter (such as EpochConverter). Most programming languages should have built in methods for date conversion as well.

    Adding/Removing Sequences and Tags

    Tags: Tags be added by either using the tag name or the tag ID, separated by */*. The syntax for each:

    <field name="Contact Tags">Tag1*/*Tag2*/*Tag3</field>
    <field name="Contact Tags" type="numeric">1*/*2*/*3<field>

    Sequences: Sequences can only be added by sequence ID. Unlike adding tags by ID, the numeric type is not required.

    <field name="Sequences">1*/*2*/*3<field>

    Removing: Tags and sequences can be removed from a contact during an update request by setting the "action" attribute to "remove".

    <field name="Contact Tags" action="remove">Tag1*/*Tag2*/*Tag3</field>

     

    When adding tags or sequences numerically, you may also separate by semicolon.

     <field name="Sequences" type="numeric">1;2</field>

    Changing Bulk Status (Unsubscribing a Contact from Emails)

    The API has the ability to set bulk email status to "No" on a contact (unsubscribing them from broadcast mailings and sequences). This is useful for making your own unsubscribe links both in OfficeAutopilot or if you're mailing from another system in addition to OfficeAutopilot and want to keep your opt outs synced between both systems.

    In order to set the bulk email status during an update request, you just need to add an extra "bulk_mail" attribute to the contact tag.

    Example:

    <contact="12345" bulk_mail="0">

    The values for bulk_mail and their associated statuses are as follows:

    0 - No/Opt-out
    1 - Single Opt-In
    2 - Double Opt-In
    -1 - Hard Bounced

    Note: The the bulk email status can only be set to "No" via the API. In order to set it to "Yes" a contact will need to resubscribe via an OfficeAutopilot form.

    Returns

    Unless otherwise noted, most requests return a simple Success or Failed message formatted as follows:

    <result><status>Success</status></result>
    <result><status>Failed</status></result> 

    Maximum Requests per Minute

    Up to 180 requests per minute are allowed per ONTRAPORT account

     

    Request Types

    Add

    Request: add

    Action: Adds a contact (along with any included field values) to the database.

    Return: Success/Failure Message (optionally returns full contact record or just contact ID and date last modified)

    Required Data: Contact object in XML or JSON format

    Optional Data: Contact object

    Example:

    Update

    Request: update

    Return: Success/Failure Message (optionally returns full contact record or just contact ID and date last modified)

    Required Data: Contact tags with Contact ID

    Optional Data: Contact object in XML or JSON format

    Example:

    Fetch

    Request: fetch

    Return: Contact record(s) of requested contact(s)

    Required Data: Contact ID(s) wrapped in contact_id tags

    Note: The "contact" element contains additional information about the contact.

    <contact id='12345' date='1339599077' dlm='1373305141' score='0.00' purl='Firstname' bulk_mail='1'>

    The included attributes are contact id, date added, date last modified, score, purl subdomain, and bulk email status. The values for bulk email status are as follows:

    -1 - Hard Bounce
    0 - No
    1 - Yes (Single Opt-in)
    2 - Double Opt-in

    Example:

    Delete

    Request: delete

    Return: Success/Failure Message

    Required Data: Contact ID(s)

    Key

    Request: key

    Return: Contact record template

    Required Data: None

    Example:

    Add Section

    Request: add_section

    Action: Adds a section to all contact records

    Return: Success/Failure Message

    Required Data: Section data

    Field Types: When creating fields, you'll need to set field type in the request. Here is a list of field types in OAP along with the associated type that needs to be set in the request

    Text - text
    Phone number - phone
    Address - text
    State - state
    Country - country
    Date - fulldate
    List selection - list
    Long text - longtext
    Check box - check
    Dropdown - tdrop
    Number - numeric
    Price - price
    Funnel - funnel

    Example:

    Edit Section

    Request: edit_section

    Action: Modifies an existing field section

    Return: Success/Failure Message

    Required Data: Section data

    Field Types: When creating fields, you'll need to set field type in the request. Above is a list of field types in OAP along with the associated type that needs to be set in the request

    Example:

    Remove Section

    Request: remove_section

    Action: Deletes an existing field section

    Return: Success/Failure Message

    Required Data: Section data

    Example:

    Remove Field

    Request: remove_field

    Action: Deletes an existing field

    Return: Success/Failure Message

    Required Data: Field data

    Add Dropdown

    Request: add_dropdown

    Action: Adds options to an existing dropdown field

    Return: Success/Failure Message

    Required Data: dropdown field data

    Example:

    Remove Dropdown

    Request: remove_dropdown

    Action: Removes options from an existing dropdown field

    Return: Success/Failure Message

    Required Data: dropdown field data

    Example:

    Search

    Request: search

    Return: Contact IDs of matching entries (if any), 0 if no results are found (optionally returns number of matching entries if "count" flag is set in post arguments)

    Required Data: Search criteria

    Search Operators:
    To run a search, surround your data with a <search> tag and use the <equation> tag for each type of query you would like to search for. Every equation requires a field, an op (operation) and a value.

    <search>
    <field>
    <operator>
    <value>

    Here are the availabe operators:
    'e' Equal
    'n' Not equal
    's' Starts with
    'c' Like (Ex: Email <op>c</op>@gmail.com will return a search of all the emails that match gmail.com)
    'k' Not Like
    'l'   Less than
    'g' Greater Than
    'm' Less Than or Equal to
    'h' Greater Than or Equal to

    The data for a standard search request would look something like this:
    <search>
    <equation>
    <field>First Name</field>
    <op>e</op>
    <value> John</value>
    </equation>
    </search>

    This returns all contacts whose first name field is equal to 'John'.

    Note: Search requests are limited to 500 results. Pagination is available for results which return more than 500 records. The "page" attribute can be added to the opening search tag to indicate the desired page number.

    Example:

    <search page='2'>
    <equation>
        <field>E-mail</field>
        <op>c</op>
        <value>@gmail.com</value>
    </equation>
</search>

    Example:

    Pull Tag

    Request: pull_tag

    Return: List of tag names in the account with corresponding ids

    Example:

    Fetch Tag

    Request: fetch_tag

    Return: List of tag names in the account

    Example:

    Fetch Sequences

    Request:fetch_sequences

    Return: List of sequence names in the account with corresponding ids

    Optional Data: Full (boolean). When set to true, full will return the public name and description along with the squence name and ID.

    Example:

    Add Notes

    Request: add_notes

    Return: Success/Failure Message

    Required Data:Contact id and note information

    Optional Data: Time stamp (Unix time format)

    Example:

    Fetch Notes

    Request: fetch_notes

    Return: All notes for the contact(s) provided

    Required Data: Contact ID(s)

    Optional Data: None

    Example:

    Add Tag

    Request: add_tag

    Action: Adds a tag to a contact

    Return: list of added tags

    Required Data: Contact ID(s), tag(s) to be added

    Example:

    Remove Tag

    Request: remove_tag

    Action: Removes a tag(s) from a contact

    Return: List of removed tags

    Required Data: Contact ID, tag(s) to be removed

    Example:

    FAQs

    Q: When I ping https://api.ontraport.com/cdata.php I get an SSL error that looks like this:

    SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

    Did your certificate expire?

    A: No. The SSL certificate problem tends to appear if your CA root certificate is out of date. A "CA" is shorthand for a "certificate authority," a third-party group responsible for handling secure connections around the web. They establish digital "certificates," which are a way of ensuring that there are valid connections between two machines. Without a certificate, the security risk between two machines is greater. When you receive this error, it likely means that your CA is out-of-date and needs to be updated. Generally, updating your OS will also update your CA and solve the problem.

     

    Q: What are the "sections" in the contact record?

    A: The Contact Record "sections" are divided between several tabs, but the tabs are not sections in and of themselves. The "sections" are shown in this image:

    contact-sections.png

    Articles in this section

    Created - Updated
    Have more questions? Submit a request

    Comments