Forms API (deprecated)
UPDATE:
We have a new and improved API for ONTRAPORT users. You can find the explanation HERE, and the interactive testing environment / documentation HERE.
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).
About the Forms API
Applies to: ONTRAPORT Plus and above.
All of our example code can be found on GitHub
Table of Contents
- Fetch - Pull hybrid code for a smart form
Introduction
The forms API currently returns the hybrid (HTML/JavaScript) version of a smart form. If no smartform ID is passed in the request, a list of all smartforms with their corresponding form IDs will be returned.
Authentication
Use of the Forms API requires an API App ID and API Key. These can be generated within your ONTRAPORT account by going to Account > ONTRAPORT 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 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, http://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 data (varies based on request type) |
A basic request should resemble the following:
Request URL:
https://api.ontraport.com/fdata.php
POST data:
appid=abc12345&key=xyz54321&reqType=fetch
Maximum Requests per Minute
Up to 180 requests per minute are allowed per ONTRAPORT account
Request Types
Fetch
Request: fetch
Return: List of forms with corresponding id's or hybrid (HTML and Javascript) version of a specific smartform
Required Data: None
Optional Parameter: form id (id=[form_id])
The fetch request works in one of two ways depending on if an optional form id is passed.
If no ID is passed in the request, the call will return a list of all forms in the account along with corresponding form IDs.
If a form ID is passed, the call will return the hybrid version of the smartform code.
<?php // Replace the strings with your API credentials located in Admin > OfficeAutoPilot API Instructions and Key Manager $appid = "XXXXXXXXXXXXXXX"; $key = "XXXXXXXXXXXXXXX"; $reqType= "fetch"; $postargs = "appid=".$appid."&key=".$key."&return_id=1&reqType=".$reqType; $request = "https://api.ontraport.com/fdata.php"; $session = curl_init($request); curl_setopt ($session, CURLOPT_POST, true); curl_setopt ($session, CURLOPT_POSTFIELDS, $postargs); curl_setopt($session, CURLOPT_HEADER, false); curl_setopt($session, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($session); curl_close($session); header("Content-Type: text"); echo $response;
<forms><form id='1'>Form 1</form><form id='2'>Form 2</form><form id='3'>Form 3</form></forms>
URL: https://api.ontraport.com/1/objects?objectID=122 Method: GET Doc: https://api.ontraport.com/doc/#!/objects/getObjects
<?php // Replace the strings with your API credentials located in Admin > OfficeAutoPilot API Instructions and Key Manager $appid = "XXXXXXXXXXXXXXX"; $key = "XXXXXXXXXXXXXXX"; $reqType= "fetch"; $postargs = "appid=".$appid."&key=".$key."&return_id=1&reqType=".$reqType."&id=25"; //optional id parameter added to URL returns form code for form matching that id $request = "https://api.ontraport.com/fdata.php"; $session = curl_init($request); curl_setopt ($session, CURLOPT_POST, true); curl_setopt ($session, CURLOPT_POSTFIELDS, $postargs); curl_setopt($session, CURLOPT_HEADER, false); curl_setopt($session, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($session); curl_close($session); header("Content-Type: text"); echo $response;
<link rel="stylesheet" href="//www1.moon-ray.com/formeditor/formeditor/css/form.default.css" type="text/css" /><link rel="stylesheet" href="//www1.moon-ray.com/formeditor/formeditor/css/form.publish.css" type="text/css" /><link rel="stylesheet" href="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.10/themes/smoothness/jquery-ui.css" type="text/css" /><link rel="stylesheet" href="//www1.moon-ray.com/v2.4/include/formEditor/gencss.php?uid=p2c1234f1" type="text/css" /><script type="text/javascript" src="//www1.moon-ray.com/v2.4/include/formEditor/genjs-v2.php?html=false&uid=p2cf25"></script><div class="moonray-form-p2c1234f1"><div class="moonray-form moonray-form-label-pos-stacked"> <form class="moonray-form-clearfix" action="https://forms.moon-ray.com/v2.4/form_processor.php?" method="post"> <div class="moonray-form-element-wrapper moonray-form-element-wrapper-alignment-left moonray-form-input-type-email"><label for="mr-field-element-108279313659" class="moonray-form-label">Email</label><input name="email" type="email" class="moonray-form-input" id="mr-field-element-108279313659"/></div> <div class="moonray-form-element-wrapper moonray-form-element-wrapper-alignment-left moonray-form-input-type-submit"><input type="submit" name="submit" value="Submit" class="moonray-form-input" id="mr-field-element-689331501256" src/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="afft_" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="aff_" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="sess_" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="ref_" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="own_" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="oprid" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="contact_id" type="hidden" value/></div> <div class="moonray-form-element-wrapper moonray-form-input-type-hidden"><input name="uid" type="hidden" value="p2c1234f1"/></div> <span class="moonray-form-clearfix"></span> </form> </div> </div>
URL: https://api.ontraport.com/1/form?id=25 Method: GET Doc: https://api.ontraport.com/doc/#!/forms/getForm
Comments