API

Most routes require at least WordPress v4.4. The view routes require v4.7+.

Send your Formidable entry data to any other site that has a REST API. This includes the option of sending entries from a Formidable form on one site to a Formidable form on another. This will also be extended to Oauth after the API is added to WordPress.

Download and install

  1. Download the latest version of the Formidable API add-on
  2. In your WordPress admin, go to 'Plugins' → 'Add New' and click the 'Upload Plugin' button at the top of the page.
  3. Upload the zip file you just downloaded in step two. Once the plugin is installed, click 'Activate Plugin' or go to the 'Plugins' page, find 'Formidable API' and click 'Activate'.

HTTP Methods

  • GET
    Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they’re safe and idempotent.
  • POST
    Use a POST request to create new entries, forms, Views, or fields. POST can also be used to update an entry, form, View, or field.
  • PATCH
    Make a PATCH request to update an entry, form, View, or field. With PATCH requests, you only need to provide the data you want to change.
  • PUT
    Use a PUT request to create or update an entry, form, View, or field.
  • DELETE
    Make a DELETE request to delete an entry, form, View, or field.

Routes

  • yoursite.com/wp-json/frm/v2/entries GET Get entries from all forms.
  • yoursite.com/wp-json/frm/v2/entries POST Create an entry.
  • yoursite.com/wp-json/frm/v2/entries POST/PUT/PATCH
  • yoursite.com/wp-json/frm/v2/entries DELETE
  • yoursite.com/wp-json/frm/v2/entries/# GET Get entry by id. # = entry ID.
  • yoursite.com/wp-json/frm/v2/entries/# POST/PUT/PATCH Update entry by id. # = entry ID.
  • yoursite.com/wp-json/frm/v2/entries/# DELETE Delete entry by id. # = entry ID.
  • yoursite.com/wp-json/frm/v2/forms/#/entries GET Get all entries in a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/#/entries POST/PUT/PATCH
  • yoursite.com/wp-json/frm/v2/forms/#/entries DELETE Delete all entries in a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/#/fields GET Get an array fields from a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/#/fields POST Create a field in a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/#/fields/# GET Get a field from a form. The first # is the form ID, and the second is the field ID.
  • yoursite.com/wp-json/frm/v2/forms/#/fields/# DELETE Delete a field from a form. The first # is the form ID, and the second is the field ID.
  • yoursite.com/wp-json/frm/v2/forms/#?return=html GET Get the form HTML to display on a page
  • yoursite.com/wp-json/frm/v2/forms GET Get an array of forms
  • yoursite.com/wp-json/frm/v2/forms POST Create a form
  • yoursite.com/wp-json/frm/v2/forms/# GET Get a single form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/# DELETE Permanently delete a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/views/# GET

Send entry data

If you would like to send entry data to another site when an entry is created, updated, or deleted, follow the instructions below.

  1. From your WordPress dashboard, pull up the form that you would like to send data from.
  2. Go to the 'Settings' → 'Form Actions' tab. Click the 'Send API data' icon to add a new API action.
  3. Insert the Notification URL for the site that you would like to send data to.
  4. Insert the Handshake key, if required, of the service that you are sending the data to.
  5. Insert the data that you would like to send in the format that the receive application is expecting.
  6. Choose when you would like this hook to fire.
  7. Make sure you are NOT using default permalinks on your WordPress "Settings" -> "Permalinks" page.
  8. Save your new action and either create, update, or delete an entry to trigger it.

Send an entry to Zapier

You can send a form entry to Zapier, using the API add-on, when an entry is created, updated, deleted, imported, or saved as a draft. If you only need to send entry data to Zapier when an entry is created or deleted, and you want a faster setup, you can install our Zapier add-on. Follow the steps below to send entry data to Zapier.

  1. Go to zapier.com and log in to your Zapier account.
  2. Click 'Make a Zap'.
  3. Select 'Webhooks by Zapier' as the Trigger App. Select 'Catch Hook' and continue. Leave the 'Pick off a child key' option blank and continue.
  4. Zapier will now provide you with a unique URL. Copy it to your clipboard. Click 'OK, I did this'.
  5. Go to your site's dashboard. Create a new form or go into edit an existing form. Go into Settings > Form Actions. Add an API action.
  6. Paste the URL from your clipboard in the Notification URL box.
  7. Put x:API-KEY-HERE in the Basic Auth box. Replace API-KEY-HERE with the API Key found in your Formidable Global Settings > API tab.
  8. Set up a few key value pairs. You may use any text you would like for the name. You may insert field ID shortcodes, static text, or other shortcodes for the value.
  9. Configure your 'Trigger Actions' as needed.
  10. Submit a new entry in your form.
  11. Go back to zapier.com. Zapier should say 'Test Successful!'. If it does not, please create a ticket in the help desk with the message that you are seeing. If you do see the success message, hit Continue and finish setting up your zap like normal.
  12. Create an entry from Zapier

    Follow the steps below to create a new entry in a Formidable form with Zapier.

    1. Create a new Zap in the Zapier dashboard.
    2. Select and configure your trigger.
    3. Select "Web Hook" and then POST for the action.
    4. Go through each step as instructed by Zapier until you get to #5 "Match up Trigger to Web Hook POST."
      • URL: http://yoursite.com/wp-json/frm/v2/entries
      • Payload Type: json
      • Data: Add a row here for each field in your form you'd like to populate. Be sure to include your form_id here as well. For now, use the field keys instead of field ids in the left column.
        zap_data
      • Wrap Request In Array: No
      • Unflatten: No
      • Basic Auth: API-KEY-HERE|x
        Replace "API-KEY-HERE" with your API key from the Formidable -> Global settings -> API page.
    5. Save your settings, and test our your Zap.

    Update an entry

    If you would like to update an entry on the same site or a different site with the API add-on, follow the steps below. Please note that Formidable and the API add-on must be installed on both sites.

    1. Go into edit the form that will send the data and trigger the entry update.
    2. Click on 'Settings' → 'Form Actions' → 'Send API Data'. This will add an API action to your form.
    3. Insert the following in the Notification URL box:
      yoursite.com/wp-json/frm/v2/entries/25

      Replace yoursite.com with the site that holds the entry you would like to update. Replace 25 with the ID of the entry to update.

    4. Insert the API key of the receiving site in the Basic Auth box.
    5. Insert key/value pairs, including only the fields that you want to update in the receiving form. Your key/value pairs may look like this:
      Keys Values
      rt2yml [2018]
      fieldkeyhere [2019]

      Make sure to use the receiving field key in the "Key" column. Use the sending field key or ID in the "Values" column.

    6. Select 'PATCH' as the Method. This will ensure that only the posted fields are updated.
    7. That's it! Now try submitting an entry in the sending form and see if it updates the entry in the receiving form.

    Create an entry in another form

    Follow the instructions below to automatically create an entry in a Formidable Form in another form or on another site when an entry is created in a Formidable Form. Please note that you must have current versions of WordPress, Formidable, and the Formidable API add-on installed on both sites.

    wordpress-form-api

    Settings to create a new entry

    1. Go into edit the form where entries will be submitted.
    2. Go to "Settings" → "Form Actions" and click the "Send API Data" icon to add an API action.
    3. Insert this in the Notification URL box:
      https://site-to-send-to.com/wp-json/frm/v2/entries
      Make sure you replace https://site-to-send-to.com with the actual URL of the site you are sending data to, or use [siteurl] if you are creating the entry on the same site.
    4. Insert your Handshake Key. The Handshake Key can be found on the "Formidable" → "Global Settings" → "API" tab on the site you are sending data to.
    5. Go to the "Data Format" box. This is where you determine which data will be sent and which fields it should go to on the second site. Click the "Insert Default" button to insert default data in the "Data Format" box.
    6. Change the form ID (in "form_id": "xx") to the ID of the form that you are sending data to.
    7. Then, add the data into your key/value settings. Use the field keys from the form you are sending data to. Use field IDs/keys in brackets to pass data from the current form. They'll look something like this:
      Keys Values
      form_id 12
      rt2yml [2018]
      fieldkeyhere [2019]

    Get a group of entries

    When you use the yoursite.com/wp-json/frm/v2/entries/25 route via GET, extra parameters are available.

    • orderby - defaults to id
    • order - use ASC or DESC. Defaults to ASC
    • page_start - set the entry number to start on. For example, if you want the third page of entries and you are getting 50 per page, insert 100 for the page_start.
    • page_size - change the number of entries returned. Defaults to 25

    Send API request with ajax

    You can fetch entries and display them on a page using javascript. This example is very basic an includes the API key. It would be best to include the API key somewhere safer.

    <script type="text/javascript">
    jQuery(document).ready(function($){
    var apiKey = 'api-key-here'; //only keep the API key here for initial testing
    $.ajax({
    beforeSend: function(request) {
    request.setRequestHeader('Authorization', 'Basic '+ btoa( apiKey +':x' ));
    },
    dataType: "json",
    url: 'site.com/wp-json/frm/v2/forms/209/entries?order=DESC&page_size=1',
    success:function(json){
      // do something with the returned entries
    },
    error: function (xhr, ajaxOptions, thrownError) {
    console.log('error');
    }
    });
    });</script>

    Send API request with PHP in WordPress

    If you are sending the API request from one WordPress site to another, you can use wp_remote_post or wp_remote_get.

    $url = 'http://yoursite.com/wp-json/frm/v2/forms/5/entries/'; // change your url
    $response = wp_remote_post( $url, array(
    	'method' => 'POST', // change this depending on the route you are using
    	'timeout' => 45,
    	'headers' => array( 'Authorization' => 'Basic ' . base64_encode( $api_key .':x' ) ),
        )
    );
    
    if ( is_wp_error( $response ) ) {
       $error_message = $response->get_error_message();
       echo "Something went wrong: $error_message";
    } else {
       echo 'Response: ';
       print_r( $response );
    }

    Show a form or View on another WordPress site

    If you have created a Formidable form or View on WordPress site #1 and you would like to publish it on WordPress site #2, you may use the frm-api shortcode.

    Shortcode usage

    [frm-api type="form" id="200" url="http://example.com"]

    Shortcode parameters

    • id: The ID of your form or View that you would like to display.
    • type: Use type="form" to retrieve a form and use type="view" to retrieve a View.
    • url: The URL of your site that holds the view/form you would like to embed.
    • get: Need to pass dynamic data from your url to the site holding the data? Include the names of any parameters in your url to pass. For example, if your url includes ?house=321&street=Lane and you want to pass 321 and street to the other site, include get="house,street" in your shortcode. Usage: get="anything,in,url"
    • Any parameter: Pass a static value to your form/View. Usage:

      [frm-api id=200 type="view" url="http://example.com" my_param="value"]

    Show a form on another WordPress site

    If you have created a Formidable form on WordPress site #1 and you would like to publish it on WordPress site #2, follow the directions below. This is helpful if you would like to store all entries on site #1.

    1. Make sure you are running the current versions of WordPress, Formidable, the Formidable API add-on on both sites.
    2. Go into edit your form (from site #1). In the Settings, check the option to 'Submit with Ajax'. Make sure the form is not limited to logged-in users. When publishing a form with the frm-api shortcode, all users (whether logged-in or out) will see what a logged-out user would see.
    3. Insert the following shortcode on WordPress site #2 (the site where you would like to publish your form):

      [frm-api type="form" id="200" url="http://example.com"]

      Replace 200 with the ID of the form that you would like to display and replace http://example.com with the URL of site #1.

    Show a View on another WordPress site

    If you have created a Formidable View on WordPress site #1 and you would like to publish it on WordPress site #2, follow the directions below.

    1. Make sure you are running the current versions of WordPress, Formidable, the Formidable API add-on on both sites.
    2. If your View is a Dynamic or Calendar View, you will need to go into edit your View and replace the detaillink shortcode with ?entry=[id].
    3. Make sure your View is public so it will be visible on site #2. The frm-api shortcode does not use authentication, meaning that it will display what a logged-out user would see on site #1.
    4. Insert the following shortcode on WordPress site #2 (the site where you would like to publish your form):

      [frm-api type="view" id="200" url="http://example.com"]

      Replace 200 with the ID of the View that you would like to display and replace http://example.com with the URL of site #1.

    5. If your View is a Dynamic or Calendar View, you will need to add get="entry" to the frm-api shortcode:

      [frm-api type="view" id="200" url="http://example.com" get="entry"]

    Show a form or a View on a non-WordPress site

    This script will pull a form or View from a WordPress site and allow you to display it on a non-WordPress site. You'll need to add the script and HTML to your non-WordPress page. You'll also need to change the text marked in red.

    <div id="frmapi-id-goes-here" class="frmapi-form" data-url="http://yourwordpresssite.com/wp-json/frm/v2/forms/id-goes-here?return=html"></div>
    <script type="text/javascript">
    jQuery(document).ready(function($){
    var frmapi=$('.frmapi-form');
    if(frmapi.length){
    	for(var frmi=0,frmlen=frmapi.length;frmi<frmlen;frmi++){
    		frmapiGetData($(frmapi[frmi]));
    	}
    }
    });
    function frmapiGetData(frmcont){
    	jQuery.ajax({
    		dataType:'json',
    		url:frmcont.data('url'),
    		success:function(json){
    			frmcont.html(json.renderedHtml);
    		}
    	});
    }
    </script>

    This script depends on jQuery, so be sure to load that on your page as well. Read more about loading jQuery on your site.

    Search across sites

    When using the version 2 API, you can easily insert forms and views on your page from another site. You can even search those inserted views.

    1. Install Formidable and this API plugin on both sites.
    2. Create a search form on the site that is embedding the view. The redirect url for the search form will include whatever parameters your view is setup to filter by. Or you can insert the basic search form with the [frm-search] shortcode.
    3. Insert your search form on the page, along with the frm-api shortcode to fetch your view. Your page will look like this for a basic search:

      [frm-search]
      [frm-api id=200 url="http://localhost.localdomain/wordpress" type=view get="frm_search"]

      See more detail on the frm-api shortcode above.

    Show the API response

    Check the response from the webhook, and add a message to the success message shown after your entry is submitted. This is based on the status the API call returns.

    add_action( 'frmapi_post_response', 'frm_get_api_response', 10, 3 );
    function frm_get_api_response( $response, $entry, $form_action ) {
      $status = wp_remote_retrieve_response_code( $response );
      if ( $status == 200 ) {
        add_filter('frm_main_feedback', 'frm_add_200_to_message' );
      } else {
        add_filter('frm_main_feedback', 'frm_add_500_to_message' );
      }
    }
    
    function frm_add_200_to_message( $message ) {
      $message .= ' The API call was successful';
      return $message;
    }
    
    function frm_add_500_to_message( $message ) {
      $message .= ' The API call was not successful';
      return $message;
    }