Form Webhooks API

Knowledge Base → Add-Ons → Automation → Form Webhooks API
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

To access this add-on, ensure you have the Business license or above.
  1. If you haven't already, install and activate the current version of Formidable Forms Premium on your WordPress site.
  2. After confirming your Formidable Forms license, proceed to the Formidable → Add-Ons page and click the Install button for the Formidable Forms API plugin.
    Form Webhooks API Install

How to find the API key

To find the API key, go to your Formidable → Global Settings and click the API tab.
Form Webhooks API Key

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.

API form action settings

  1. Go into your form to set up the API. Click on form Settings → Actions & Notifications → Send API Data.
    Form Webhooks Send API Form Actions
  2. Give your Send API data form action an Action Name for easy reference. This name is only visible on the back end.
    Form Webhooks Send API Form Settings
  3. In the Trigger this action when dropdown, select an option if you want the entry to be created, updated, deleted, imported, or saved as a draft.
  4. Insert the Notification URL for the site where you want to send the data.
  5. Insert the API Key in the Basic Auth box. You can test the connection by clicking the Test Connection button. A colon (:) separates the username and password combo for standard HTTP authentication. The key is provided by the service you are connecting to, if required.
  6. Set the Data Format to JSON, form, or raw.
    • JSON: It is a standard format for most REST APIs.
    • Form: This option will submit a form on another page with any name-value pairs of your choosing.
  7. Set the Method property to POST, GET, PUT, PATCH, DELETE. The method determines how the data is handled on the receiving end.
    • POST = create
    • GET = read
    • PUT/PATCH = update
    • DELETE = delete
  8. Set the Character Set to use blog charset, UTF-8, ASCII, and ANSI. Character Set is a defined list of characters recognized by the computer hardware and software.
  9. Set up a few key-value pairs to map your data. 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.

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

Entries

  • 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

Forms and Views

  • 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 PATCH Update multiple fields. # = 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/#/fields/# PATCH Update a single field. 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 Get a single View. # = view ID.

Stats
Where {field_id} can be field keys or a comma separated list of field IDs/keys.

  • yoursite.com/wp-json/frm/v2/stats/total/{field_id} GET Get the total stats.
  • yoursite.com/wp-json/frm/v2/stats/count/{field_id} GET Get the count stats.
  • yoursite.com/wp-json/frm/v2/stats/average/{field_id} GET Get the average stats.
  • yoursite.com/wp-json/frm/v2/stats/median/{field_id} GET Get the median stats.
  • yoursite.com/wp-json/frm/v2/stats/star/{field_id} GET Get the star stats.
  • yoursite.com/wp-json/frm/v2/stats/maximum/{field_id} GET Get the maximum stats.
  • yoursite.com/wp-json/frm/v2/stats/minimum/{field_id} GET Get the minimum stats.
  • yoursite.com/wp-json/frm/v2/stats/unique/{field_id} GET Get the unique stats.
  • yoursite.com/wp-json/frm/v2/stats/deviation/{field_id} GET Get the deviation stats.

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: 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.
      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 Webhooks API - Create API 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: 
    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 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.

Keys Values
y [x]

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 using default shortcode

If you would like to use default shortcodes as values when mapping fields for your API form action, your key/value pairs may look like this:

Key Value
form_id 22
191 [date]
192 [user_id]
193 [created_at]
194 [updated_at]

Where 22 is the ID of the receiving form, and 191, 192, 193, 194 are the field ID/keys in the receiving form. Your data received will look something like this:

{
"date": "2023-09-11",
"user_id": "harry",
"created_at": "2023-09-11 at 2:55 pm",
"updated_at": "2023-09-11 at 2:59 pm"
}

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

Find the ID of a repeater

You can find the repeater (child) form ID by following the steps below.

  1. Go to Formidable → Import/Export.
  2. Select CSV as the Export Format.
  3. Using the search bar, type in and search for the name of your repeater section.
  4. Under the Type column, you will see Child Form (x), where x is the ID of the parent form.
    child-form-id-and-parent-form-id
  5. Under the ID/Form Key column, you will find the child form ID.

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:

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

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: 
    https://site-to-send-to.com/wp-json/frm/v2/entries/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 a repeater

Sending an entry from a form without a repeater into a repeating field in another form requires the following setup.

  1. Instead of using the JSON format option, select raw.
  2. Your data will look something like this: 
    {
"s499o": {    
"form": 890,
"0": {
"8702": "[21455]",
"18300": "[8635]"
}
},
"form_id": 348
}
  3. Take note of the following:
    • Replace s499o with the key of your repeating field.
    • Replace 890 with the ID of the child form
    • Do not change 0.
    • Use field IDs instead of field Keys.
    • Replace 8702 and 18300 with the IDs of the fields in your repeater.
    • Replace 21455 and 8635 with the IDs of the fields in the sending form.
    • Replace 348 with the ID of the receiving form, where your repeating field is located.

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

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.

Create an entry from Postman

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

  1. Download Postman and create a new HTTP request by clicking the New button in the top left corner of the window.
    Form Webhooks Postman New Request
  2. Set the request type to POST by selecting it from the dropdown in the settings.
    Form Webhooks Postman Create entry
  3. In the URL field, enter the URL of your WordPress site, followed by /wp-json/frm/v2/entries.
  4. Select Body from the tab menu of the request. Choose raw and JSON as the type from the dropdown below it. Add key/value pairs for the data you would like to send.
    Keys Values
    form_id 860
    18911 Hello world

    Your data may look like this in raw format: 

    { 
"form_id": "860",
"18911": "Hello world"
}

    Replace 860 with your form ID and 18911 with the ID of your field in the form.

  5. Select Auth from the tab menu of the request. Choose Basic Auth as the type from the dropdown below it.
    Form Webhooks Postman Create Basic Auth
  6. Enter your API key as the username and x as the password.
  7. Click the Send button to initiate the request.

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 would like to publish it on WordPress site #2, you may use the frm-api shortcode. Use the Embed form modal to copy the auto-generated [frm-api] shortcode specific to a form.
Form Webhooks API Form 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"
  • exclude_script: A comma-separated list of WordPress script names to exclude from the API response. Usage: exclude_script="jquery"
  • exclude_style: A comma-separated list of WordPress stylesheet names to exclude from the API response. Usage: exclude_style="admin-bar-css"
  • 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

To display a Formidable form on a different WordPress site, follow the steps below. This can be particularly useful if you plan to store all form entries on the first site.

  1. Ensure that both WordPress sites are running the latest versions of WordPress, Formidable, and the Formidable API add-on.
  2. On WordPress site #1, go to the form you want to use and navigate to Form Settings → General. Select the option to Submit this form with Ajax. Also, ensure that the form visibility is not restricted to logged-in users.
  3. Access the Embed form modal and select Insert manually.
    Embed Form Modal Insert Manually
  4. Copy the API Form Script.
    Form Webhooks API Form Script
  5. Finally, paste the API form script onto a page on WordPress site #2, where you want to display the form.

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 using embed script

If you have created a Formidable form on a WordPress site and would like to publish it on a non-WordPress site, use the embed script. As of version 1.10, using the embed script will allow you to pull a form and embed it directly into the page, similar to how the [frm-api] shortcode worked. If you have a form with a payment action, reCAPTCHA field, or have set your permalinks settings to plain, it will automatically use an iframe.

✍ Notes:

  • Currently, URL parameters are not supported when using the API Form Script.
  • When the iframe is used, the theme loads inside the iframe. This means you might notice additional theme styling that you wouldn't otherwise see in the embedded form.
  • When the iframe is implemented, it verifies whether a landing page has been designated for the form and uses it as the default fallback.

  1. Check if you are running the current versions of Formidable and the Formidable API add-on on your WordPress site.
  2. Go into your form and access the Embed form modal.
  3. Click Insert manually and copy the API Form Script that you can use to embed your form in any non-WordPress site.
    Form Webhooks API Form Script

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="http://localhost.localdomain/wordpress" 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 
    https://ws.detectlanguage.com/0.2/detect?q=[x 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.

Using Application Passwords

Creating an application password in WordPress is an alternative way to authenticate with the API instead of using an API key. This allows you to use your username and the application password you created to access data stored in Formidable Forms. Learn more about using Application Passwords for API authentication.

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. If you need to reset the API key, it can be done from phpMyAdmin or by using the option below.

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. Use the frmapi_post_response hook to show the API response.

Save a value from the response

After an API request is sent, a response is often returned. Use the frmapi_post_response hook to save that response into a field in the entry.

Customize API request headers

Use the frm_api_request_args hook to customize the headers sent with your API request.

Convert a meta value to an int

Use the frm_api_request_args hook to convert a specific "owner_id" meta value to an integer when sending API data.

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

Increase timeout for API actions

By default, there is a 15 second timeout for API actions. Use the frm_api_request_args hook to increase the timeout for API actions.

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. To ensure your Basic Authentication setup works correctly on your server, try deleting a post from your WordPress site using Postman. If the post is successfully deleted, your Basic Auth setup works as expected. If the post is not deleted, you may need to adjust your htaccess file to ensure that Basic Authentication functions correctly on your server.

  1. Download Postman and create a new HTTP request by clicking the New button in the top left corner of the Postman window.
    Form Webhooks Postman New Request
  2. Set the request type to DELETE by selecting it from the dropdown menu in the settings.
    Form Webhooks Postman Delete Basic Auth
  3. In the URL field, enter the URL of your WordPress site, followed by /wp-json/wp/v2/posts/##, where ## is the ID of the post you want to delete.
  4. Select the Auth tab of the request, and choose Basic Auth as the type from the dropdown menu.
  5. Enter your API key as the username and x as the password.
  6. Click the Send button to initiate the request.
    • 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, follow the logging guide 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 Formidable Logs add-on 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.

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.

Examples

Use this guide to add your contacts in Brevo (SendinBlue) when an entry is created or updated in the Formidable Form.

Categories
×

Categories

Using WordPress and want to get Formidable Forms for free?

Get Formidable Forms Lite Now

This article may contain affiliate links. Once in a while, we earn commissions from those links. But we only recommend products we like, with or without commissions.

Take on bigger projects Right Now

Get the tools you need to revolutionize your workflow and architect a masterpiece. Build the most advanced WordPress forms and actually use the data you collect in meaningful ways.

Get the most advanced WordPress form plugin and the only form builder with integrated Views.

Get Formidable Forms Now