Formidable Forms API for extendable WordPress forms

Form Webhooks Api Key
  • Description
  • FAQ
  • Screenshots
  • DEMO
  • Updates & Support

Heads up!
This article contains Advanced API principles and examples intended for developers and those familiar with APIs. We offer these examples as a courtesy, but don’t provide support for customizations, troubleshooting or 3rd party development.

Send your Formidable entry data to any other site that has a REST API. It is set up to send requests using Basic Authorization. This includes the option of sending entries from a Formidable form on one site to a Formidable form on another.

Note: When there is no API key passed, all API requests are treated as logged-out users and there isn’t currently a built-in solution to pass user info or roles along with an individual request. When the API key is passed, the request is performed as an administrator.

The view routes require WordPress v4.7+.

Download and install

  1. If you haven’t already done so, install and activate Formidable Forms Pro.
  2. In your WordPress admin, go to ‘Formidable’ → ‘Add-Ons’ and click the ‘Install’ button for the Formidable form API plugin.

How to find the API key

To find the API key, go to your ‘Formidable’ → ‘Global Settings’ and click the ‘API’ tab.

API key information

The API key is generated when you install the Formidable API add-on and is stored in the wp_options database table as frm_api_key. It has 19 characters by default and it would take billions of years to make a request via the API by guessing it with brute force. We do not use a password on top of the API key (in the examples below x is used as a placeholder). It is strongly recommended to use SSL (“https”) on your server if you will be using the API add-on to send or receive requests.

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, or fields. POST can also be used to update an entry, form, View, or field.
  • PATCH/PUT
    Make a PATCH or PUT request to update an entry, form, or field. With PATCH and PUT requests, you only need to provide the data you want to change.
  • DELETE
    Make a DELETE request to delete an entry, form, 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/# 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/#/fields GET Get an array fields from a form. # = form ID.
  • yoursite.com/wp-json/frm/v2/forms/#/fields POST Create fields in a form. # = form ID. See create fields in a form for more information.
  • 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

Entries

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’ → ‘Actions & Notifications’ 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 plain 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 to ‘Settings’ → ‘Actions & Notifications’. Add an API action.
  6. Paste the URL from your clipboard in the Notification URL box.
  7. Put API-KEY-HERE:x in the Basic Auth box. Replace API-KEY-HERE with the API key.
  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.

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:
    • 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.
      Formidable Forms Api 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 out 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’ → ‘Actions & Notifications’ → ‘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. You can also get the entry ID dynamically with a View. For example, you could create a Single Entry View from the form you will be updating, place [id] in the Content, and add a filter that says something like “UserID is equal to [get param=u_id]”. You could then insert this in your Notification URL:

    yoursite.com/wp-json/frm/v2/entries/[display-frm-data id=x u_id="[y show=ID]"]

    Replace x with the ID of the View and replace y with the ID of the userID field in your current form. This would update the first entry created by the current user. Note: This will only work if you are updating an entry on the same site, but not if you are updating an entry on another site.

  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.

Note: If you are sending along date field values, make sure that you use [x format=”Y-m-d”] in the shortcode.

Auto delete an entry after a specific date

If you want to automatically delete an entry using the API add-on after a specific date or time period has passed, follow these instructions. Note that this requires the Form Action Automation add-on.

Registration forms and the API

If you are using user registration in a form on the receiving end of an API call, a couple of extra parameters are required. This tells Formidable which fields should be used for registration. If you have a password field in the form and are editing an entry with an API call, this will prevent required errors for that password.

Keys:                        Values:
frm_register|reg_email       25
frm_register|reg_username    26
frm_register|reg_password    27

Change 25, 26, and 27 to the IDs of the fields in the receiving form. This should match up with your registration settings in the form the API call is being sent to. These are literal ids and not values from the form.

Then go the the registration settings on the receiving site and check the box to ‘Allow logged-in users to create new users with this form.’

Note: Updating a registration entry via API without a password value isn’t yet supported.

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’ → ‘Actions & Notifications’ and click on ‘Send API Data’ to add an API action.
  3. Insert this in the Notification URL box:
    
    

    Make sure you replace 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 the API key of the receiving site in the Basic Auth box.
  5. Insert key/value pairs, starting with the ID of the form you are sending the data to. Below the form_id key/value pair, you will add the fields that you want to fill in the receiving form. Make sure to use the receiving field key in the ‘Key’ column. Use the sending field key or ID in the ‘Values’ column. Your key/value pairs may look like this:
    Keys Values
    form_id 12
    rt2yml [2018]
    fieldkeyhere [2019]

    Replace 12 with the ID of the form that you are sending data to.

  6. Select ‘POST’ as the Method.
  7. That’s it! Now try submitting an entry in the sending form and see if it creates an entry in the receiving form.

Note: If you are sending along date field values, make sure that you use [x format=”Y-m-d”] in the shortcode.

API formatting in address field

If you would like to send values from one address field to another using the API add-on, your data may look like this in JSON mode:

Keys Values
727|line1 [25 show=line1]
727|line2 [25 show=line2]
727|city [25 show=city]
727|state [25 show=state]
727|zip [25 show=zip]
727|country [25 show=country]

Or in raw format, your data will look something like this:

"727":
{
"line1": "123 Main",
"line2": "",
"city": "City",
"state": "Alaska",
"zip": "23434",
"country": "United States"
}

Change 727 to the address field ID in the receiving form and 25 to the address field ID in the sending form.

API formatting in credit card field

If you would like to send values to a credit card field using the API add-on, your data may look like this in JSON mode:

Keys Values
tmui1|cc 4242424242424242
tmui1|month 12
tmui1|year 2024

Replace tmui1 with the field key of your receiving address field. Values sent to a Credit Card field in this way will not trigger a payment, and will only save the credit card information if the field is set to store information.

Note: For security reasons, the CVC will never be stored. Credit Card fields using Stripe are not compatible with storing the credit card info.

Important!
If you are sending credit card information, you need much stricter PCI compliance on your site. If your site is not PCI compliant, do not send or store credit card information.

API formatting in file upload field

If you would like to send a file uploaded in one form to a file upload in another form, you must pass the file URL to the receiving form.

Replace y with the field key or ID of the receiving file upload field, and x with the ID of the sending file upload field.

API formatting in checkbox field

If you would like to send data to a checkbox field, you can send a comma-separated string of values to be checked in the receiving checkbox field. The values must match exactly. See below example of sending with raw format:

"7225": "Option 1, Option 2, New Option"

This will check “Option 1”, “Option 2” and “New Option” in the checkbox field with ID 7225.
Replace 7225 with the field key or ID of the receiving checkbox field, and each option with a checkbox value you want checked.

API formatting in User ID field

If you are sending data from a User ID field to another User ID field on the same site or a different site, use [x show=email]. That way, if the user is on the same site it will be linked up correctly. If you are sending to a different site, the user will also be linked up if it exists.

Send value to a field with auto_id shortcode

If you need to create an entry in a form that uses the auto_id shortcode, it is necessary to include a value for the key that goes to the field containing the [auto_id] shortcode. A value of 1 will do the job.

Add values in a repeater

  1. Instead of using the JSON format option, select ‘raw’.
  2. Your data will look something like this:
    {
    "field1": "[270]",
    "field2": "[271]",
    "section1": {
    "form":32,
    [foreach 279]
    "[id]":{
    "300": "[280]",
    "301": "[281]"
    },
    [/foreach 279]
    "":""
    },
    "form_id": 31
    }

    Note:The [id] in the data is meant to stay as [id]. It is a shortcode that autofills with the ID of the entry that is being submitted. Don’t remove this or change its value.

    Change the following values:

    • field1 & field2 = Field keys in the receiving form. Use field ids or keys.
    • 270 & 271 = Field keys in the sending form. Use field ids or keys.
    • section1 = The field key of the repeater field in the receiving form
    • 32 = The id of the repeater child form. This value is tricky to find. As of Formidable v3.0, this is not needed.
    • 279 = The id of the repeater in the sending form. Use the field id or key.
    • 300 & 301 = The field IDs of fields inside the repeater in the receiving form. Use field ids.
    • 280 & 281 = Field ids inside the repeater in the sending form. Use field ids or keys.
    • “”:”” = A necessary row of dummy data so that the API request is formatted correctly. Note: If you are sending to required fields inside the receiving repeater, you will either need to modify this row to send dummy data to the actual fields inside the repeater, or mark the receiving fields as not required.
    • 31 = The id of the receiving form

Update a row in a repeater

In order to update a row in a repeater in another form, you’ll first need to have a few important items:

  • The repeater (child) form ID
  • The entry ID of the parent entry (the entry that contains the repeater that you want to update)
  • The entry ID of the child entry (the entry in the repeater itself)

You can get find the repeater (child) form ID by going to Formidable → Import/Export. Under the Export section, search for the name of your repeater section. In this row, you’ll see Child Form (x) where x is the ID of the parent form. Under the ID/Form Key column, find the child form ID. This is the first item you will need. See the screenshot below.
Child-Form-Id-And-Parent-Form-Id

For the next two items, the easiest way is to create a View for the repeater. In this view, insert [id] and [parent_id]. When you preview the view, [id] will show the entry ID of the repeater row, and [parent_id] will show the entry ID of the parent entry. See the screenshot below for an example of the view content.
Child-Form-View-Content

Now we can update a row. Follow these instructions to set up the API form action:

  1. Go to the form you want to update a row from.
  2. In Form Settings → Actions & Notifications add a Send API data form action.
  3. Insert this in the Notification URL box:
    /CHILD_ENTRY_ID

    and change CHILD_ENTRY_ID for the entry ID of the child entry we found with the view earlier. Since shortcodes are allowed here, you could make the entry id dynamic using a View that returns just the id of the entry you need.

  4. Insert your API key in the Basic Auth box
  5. Set the Data Format to raw
  6. The Raw Data box should look something like this:
    {
        "500": "[1557]",
        "parent_item_id": 150,
        "form_id": 40
    }
    1. Change 500 to the field ID of a field in the repeater form.
    2. Change 1557 to the field ID of the field you are using to update or the value you want to send
    3. Change 150 to the entry ID of the parent entry.
    4. Change 40 to the repeater (child) form ID from the Import/Export page.
  7. Add any other fields you want to update in the repeater row in the raw content, along with the value to go along with it. Don’t forget commas!

When the form is submitted, the specified row in the repeater will be updated.

Create a row in a repeater

Adding a row in a repeater that already contains entries is a bit more complex than updating a row, and requires a bit of custom code, as well as knowing the form ID of the child (repeater) form. You can follow the instructions above on how to find the child form ID. Once you have that, follow the instructions below.

  1. Create an API form action in the form you are sending from. Use the following key/value pair example below:
    Key Value Explanation
    form_id 426 Where 426 is the ID of the child form
    5662 [1557] Where 5662 is the field ID of a receiving field in the repeater to which you are sending. Repeat this row for each field in the repeater, and replace 1557 with the field ID of the corresponding field from the sending form.
    parent_item_id [510 show=”id”] Where 510 is a dynamic field ID, or replace [510 show=”id”] with an actual entry ID of the entry containing the repeater field you wish to add a row to, e.g. 19228.

    At this point, if you submitted the form, an entry would be created in the child (repeater) form, but wouldn’t yet be linked to the parent entry.

  2. Add the following code example to your site. Make sure to change the indicated values.
    add_action( 'frmapi_post_response', 'frm_save_api_response_for_repeater', 10, 3 );
    function frm_save_api_response_for_repeater( $response, $entry, $form_action ) {
    $body = json_decode($response['body'], true);
    $returned_id = $body['id']
    if ( $body['form_id'] == 426 ) { // change 426 to the ID of the child form
    $field_id = 5660; // change 5660 to the repeater field ID
    $current_entry = FrmEntry::getOne( $body['parent_item_id'] );
    $current_value = FrmEntryMeta::get_meta_value( $current_entry, $field_id );
    $current_value[count($current_value)] = $returned_id;
    FrmProEntryMeta::update_single_field( array(
    'entry_id' => $body['parent_item_id'],
    'field_id' => $field_id,
    'value' => $current_value,
    ) );
    }
    }

    The above example will update the parent entry so that it is linked to the newly created child form entry.

Now you should be fully set up and ready to create new rows in a repeater via the Formidable API.

Add an entry in a form containing an embed form

Sending an entry from one Formidable form to another that contains an embed form is a complicated process that requires the Form Action Automation add-on, a code example, and two API form actions. Follow the instructions below to set this up.

  1. Create an API form action in the sending form. This action will send to all fields in the receiving form that are not inside the embed form. Set this up according to these instructions.
  2. Add a hidden field to the sending form. This field will use a code example to save the entry ID of the entry created with the first API form action.
  3. Create a second API form action in the sending form. This action will send to the embedded form that is contained in the form you are sending data to. Follow the key/value pairs in the table below for how to set this up.
    Key Value Explanation
    form_id 59 Where 59 is the ID of the embedded form
    tmui1 [509] Where tmui1 is the field key of a receiving field in the embedded form
    parent_item_id [510] Where 510 is the field ID of the hidden field created in step 2
  4. Add automation to the second API form action. Set it to “Ignore” the action trigger, and instead trigger 1 minute after “Create Date”.
  5. Add the following code example to your site. Make sure to change the indicated values.

    add_action( 'frmapi_post_response', 'frm_save_api_response_for_embed', 10, 3 );
    function frm_save_api_response_for_embed( $response, $entry, $form_action ) {
    $body = json_decode($response['body'], true);
    $returned_id = $body['id'];
    if ( $body['form_id'] == 59 ) { // change 59 to ID of the form that is embedded
    // embed form updated
    FrmProEntryMeta::update_single_field( array(
    'entry_id' => $body['parent_item_id'],
    'field_id' => 506, // change to the ID of the embed field (not the embed form ID)
    'value' => 'a:1:{i:0;i:' . $returned_id . ';}',
    ) );
    }
    if ( $returned_id && $body['form_id'] == 63 ) { // change 63 to the ID of the form containing the embed form
    // form containing embed updated
    FrmProEntryMeta::update_single_field( array(
    'entry_id' => $entry->id,
    'field_id' => 510, // change to the ID of the hidden field in the sending form
    'value' => $returned_id,
    ) );
    }
    }

    The above example will link the entry in the embed form to the entry created in the parent form.

  6. That’s it! If properly set up, when an entry is submitted, an entry will be created in both the embedded form and the form containing it, and the two will be correctly linked together.

Get a group of entries

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

  • order_by – defaults to id
  • order – use ASC or DESC. Defaults to ASC
  • page – The page number to retrieve. Defaults to page 1.
  • page_size – change the number of entries returned. Defaults to 25
  • search – Search all fields in the entries for a value. No default.
  • start_date – Filter by the date an entry was created. Any PHP string format is allowed ie ‘7 days ago’ and 2020-03-01.
  • end_date – Filter by the date an entry was created. Any PHP string format is allowed ie ‘7 days ago’ and 2020-03-01.

Example:

yoursite.com/wp-json/frm/v2/forms/25/entries?search=john@doe.com

The above will return entries in form 25, where any field contains john@doe.com.

Send API request with ajax

You can fetch entries and display them on a page using javascript. This example is very basic and 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",
method: "GET"
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>

Update an entry with ajax

Copy the example above and follow the next steps:

  1. Set the method property to POST method: “POST”
  2. Add a data property with the same key value pairs you’d use with the action — the key of the field you want to update with the value to which you want to update it. data: { “5218”: “very happy” } swap out 5218 for the id of the field you want to update.
  3. The URL is: https://yoursite.com/wp-json/frm/v2/entries/84434. Swap out 84434 for the id of the entry you want to update.

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=" // 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 );
}

Send subsequent API requests

There may be situations where you want one entry to send two requests, but make sure one triggers a set period of time after the other. For example, you may want to make a request, save a value from the request in your form, and then use that saved value to make another request after. This can be done using the Form Action Automation add-on.

  1. Add your first API action.
  2. Use this example to save a value from the response in a field.
  3. Add your second API action. Follow these instructions to set the action to trigger 3 minutes (or any desired time period) after form submission.
  4. Include the saved value from the first request that is saved in a field in the second request.
  5. Submit an entry in the form, the first API action will trigger, and 3 minutes later the other API action will trigger, and the value saved from the first response will be saved as well.

Forms and Views

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="

Shortcode parameters

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="

    Replace 200 with the ID of the form that you would like to display and replace 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="

    Replace 200 with the ID of the View that you would like to display and replace 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="" 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.

  • To retrieve a form, use yoursite.com/wp-json/frm/v2/forms/id-goes-here?return=html
  • To retrieve a View, use yoursite.com/wp-json/frm/v2/views/id-goes-here?return=html
<div id="frmapi-id-goes-here" class="frmapi-form" data-url="http://yoursite.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=" type=view get="frm_search"]

    See more detail on the frm-api shortcode above.

Create a form

Use the yoursite.com/wp-json/frm/v2/forms/25 route via POST to create a form.

  • fields – an array of the fields to create in the form. See “Create fields in a form” below.

Create fields in a form

  • fields – an array of the fields to create in the form. Each item in the array can include field settings.
    • type – The type for this field ie ‘text’, ‘hidden’, ‘textarea’…. Required. No default.
    • name – The label for the field. Defaults to field type name.
    • description – The optional field description.
    • required – Boolean. True if the field is required. Defaults to not required.
    • field_order – Defaults to one higher than the previous field.
    • field_key – The unique field key. Autogenerated by default.
    • options – An array of choices for a radio, dropdown, or radio field. Defaults to blank.

For example:

{
"fields": [
	{
		"type":"text",
		"name":"First name"
	},
	{
		"type":"radio"
		"description":"select a radio button"
		"required":1
		"options":["one","two"]
	}
]
}

Get a group of forms

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

  • order_by – Defaults to form creation date
  • order – Use ASC or DESC. Defaults to ASC
  • page – The page number to retrieve. Defaults to page 1.
  • limit – Change the number of forms returned. Defaults to 20.
  • search – Search the form name and description. No default.
  • return – Get the form object by default, or get the rendered HTML with return=html.
  • exclude_script – If the form is rendered as HTML, selectively exclude specific scripts.
  • exclude_style – If the form is rendered as HTML, selectively exclude specific styles.

Other API routes

In addition to sending API calls to the Formidable API, the API form action can be used to send REST API calls to other APIs. This includes sending a request to the WordPress API. Below are some examples of other ways you can use the API add-on.

Create a WordPress post

The API can be used by logged in users to trigger API calls on the same WordPress site. If there is a reason to use the API instead of the regular post creation, follow these steps.

  1. Go to the form settings page for your form and add a ‘Send API data’ form action.
  2. In the Notification URL box, add
    [siteurl]/wp-json/wp/v2/posts/
  3. The Basic Auth box can be left empty when sending a request on the same site while logged in.
  4. Add key/value pairs for all the API post parameters you would like to send. For example, a basic post may include these values:
    Keys Values
    title [2018]
    content [2019]
    status draft
  5. Select ‘POST’ as the Method.
  6. Submit your form, and the post will be created.

Connect to a third-party API

The Formidable API add-on can be used to communicate with external APIs. You can find lists of free APIs and communicate with them from the Formidable API. Below is one example of connecting to an external API. In this example we will connect with the DetectLanguage API.

Note: Our support does not cover calling external APIs. This is meant to be a starting point and not a comprehensive example. Since APIs vary widely, use the principles in this example as a guideline of how to call other APIs.

  1. Create a new form with a text field for entering the language to be validated.
  2. Go to the form settings page for your form and add a Send API data form action.
  3. In the Notification URL box, add
     sanitize_url=1]

    Replace x with the field containing the language you want to validate.

  4. Create a free account on detectlanguage.com and get your API key on your account page.
  5. In your Send API Data action, insert your API key in the Basic Auth box.
  6. Select ‘POST’ as the Method, and ‘raw’ as the Data Format.
  7. By default, Formidable API includes a Content-type header. Some APIs like DetectLanguage don’t like extra headers, so it may need to be removed. Use this code example to remove it:
    add_filter( 'frm_api_request_args', 'my_custom_frm_api_request_header', 10, 2 );
    function my_custom_frm_api_request_header( $arg_array, $args ) {
        $url = "ws.detectlanguage.com";
        if (strpos($args['url'], $url) !== false) {
          $arg_array['headers']['Content-type'] = NULL;
        }
        return $arg_array;
    }
  8. Submit your form, and the field specified in step 3 will be sent to DetectLanguage.
  9. You may be wondering how to see the response. The Logs add-on will help to see the responses. If you want to save the language of the field in another hidden field for example, you can use this example.

Other authentication

The Formidable API add-on is set up to send requests using Basic Authorization. Some other types of Authorization aren’t built-in, but can be added with a hook. For example, some APIs require Bearer Authentication. If you need to communicate with an API that uses Bearer Authentication, you can add a Bearer header to the API request using this hook.

Reset the API key

The API key is saved in the wp_options table with the meta_key ‘frm_api_key’. The API key will be regenerated if it is deleted. This can be done from PhpMyAdmin or with

delete_option( 'frm_api_key' )

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;
}

Save a value from the response

After an API request is sent, a response is often returned. Use this example to save that response into a field in the entry. You must include a default value in this field (like 0) so it can be updated.

add_action( 'frmapi_post_response', 'frm_save_api_response', 10, 3 );
function frm_save_api_response( $response, $entry, $form_action ) {
  $returned_id = $response['body']['CHANGEME']; // this line will change based on the API you are sending to
  if ( $returned_id ) {
    FrmProEntryMeta::update_single_field( array(
      'entry_id' => $entry->id,
      'field_id' => 25, // change to the ID of the field to change
      'value'    => $returned_id,
    ) );
  }
}

Customize API request headers

Use the following code to customize the headers sent with your API request.

add_filter( 'frm_api_request_args', 'my_custom_frm_api_request_header', 10, 2 );
function my_custom_frm_api_request_header( $arg_array, $args ) {
    if ( $args['url'] == ' ) { // the full url where the request is being sent
        $arg_array['headers']['my_header_name'] = 'my_header_value';
        $arg_array['headers']['another_header_name'] = 'a_header_value';
    }
    return $arg_array;
}

Convert a meta value to an int

Use the following code to convert a specific “owner_id” meta value to an integer when sending API data.

add_filter( 'frm_api_request_args', 'my_custom_function' );
function my_custom_function( $args ) {
	$body = json_decode( $args['body'], true );

	if ( isset( $body['owner_id'] ) ) {
		$body['owner_id'] = (int) $body['owner_id'];
		$args['body'] = json_encode( $body );	
	}

	return $args;
}

Include password in API GET request

Use the following code example to include a specific password field in API requests. This filter can be used to include a normally excluded field from an entry table, including credit card fields.

add_action( 'rest_api_init', 'initialize_inclide_password_in_api' );
function initialize_inclide_password_in_api() {
    add_filter( 'frm_include_field_in_content', 'include_password_in_api', 10, 2 );
}

function include_password_in_api( $include, $field_value ) {
    $target_field_key = 'utv62'; // change this
    if (  $target_field_key === $field_value->get_field_key() ) {
        $include = true;
    }
    return $include;
}

Troubleshooting

Is the API accessible?

  1. Visit yoursite.com/wp-json/ to check that the WordPress API is functional and accessible. You should see a page of text when visiting this url on your site. If you see the page of text, continue to the Postman test below.
  2. If you are redirected to a login page, the plugin/code forcing the login redirect is blocking access to the API. The offending plugin will need to be deactivated.
  3. If you see the home page, there are two possible explanations: pretty permalinks have not been turned on in your WordPress settings, or there is a plugin conflicting. Once you are able to see the text page, then test your form again. If the API call still fails, continue to the Postman test below.

Postman test

Postman is one of the most helpful tools for troubleshooting and testing APIs that we have seen. Start by downloading it and running your test through their interface.

If you get a 403 response with a Postman test, follow the Basic Authentication instructions below.

If the test is successful and returns the correct result, continue to logging below.

Logging

The hardest part of sending API calls with a form action, is that it’s difficult to see what is happening. If an API call isn’t successful, install the Logging plugin and follow the instructions on that page. This will tell you when an API call is firing, where it is going, and the response. The ‘frm_message’ section in the logs includes the simplified response to help you make adjustments to the settings for the API call.

If you don’t have a Business license package or higher, download it from Github.

Testing connection

The errors shown when a test connection is tried are not a true indication. The test connection link you see only tells you if that link is reachable in many cases. Depending on the API you are sending to, it will not return a successful response when the data is not included.

Try a true test by submitting the form. If you still have trouble after that, continue to the troubleshooting steps.

cURL error 6: Could not resolve host

If you are seeing this error, then there is most likely an issue that you will need to resolve with your host. There is likely an issue with the DNS resolving correctly on your live site. If you contact your host they can look into the issue further.

409 status

If you get a 409 response in your log entry, then you have fields that are missing values. This will cause the entry to not be created. Please follow the steps below to resolve the issue.

  1. In your API form action, add values for those missing fields.
  2. Turn off confirmation fields in your receiving form, if any.
  3. You can use the Logs add-on to see the error messages that show the validation messages.

403 error

Basic Authentication

The Formidable API uses Basic Authentication. Some servers do not have Basic Authentication enabled by default. In these cases, you will get a 403 response along with an error message like: “Sorry, you are not allowed to [create,update,delete] entries.” Please see more troubleshooting steps for setting up and verifying Basic Authentication.

or
Shopping Cart
  • Your cart is empty.
Scroll to Top