The REST connector automatically sends form entry data in XML or JSON format to a web service address that you specify. It allows you to integrate with us on an event level. For example, whenever a new form entry is received by us, you will receive the data on the nominal REST verb - e.g. POST.

Your web service will need to implement the API that we specify in order to understand the data we send by default. Alternatively, you can define your own custom request body to match into existing APIs endpoints that you wish to send form entry data to.

Technical staff should see our Form Entries API documentation for further information.

Adding the connector

The connectors page can be accessed from your form design, settings or screens listing. Hover over the form you wish to add a connector to. 

1. Click on 'ADD CONNECTOR' in the top right to see a list of the available connectors. Click the REST option. 


2. This will refresh the page and display your connector, ready for configuration.

Note: You must click the 'Save' button to save your connector after you've finished setting it up.

3. Specify the desired request format for example JSON or XML.

and the desired REST verb (usually POST)

4. If you are sending form entry data into an existing external service API you will need to customize the request body to match this. Click the 'customize body' link to reveal a text area that you can use to define the request format, injecting your form fields using the same #{{ }} syntax you would use to create a data template. Doing this will provide you with the ability to plug into almost any external service that exposes a REST API.

Read up on API documentation to learn more about the required data structure and submission endpoints, then plug those into your REST connector url and body.

5. Specify the destination URL to which our platform will POST data. You can enter an address directly into the given field, or you can click the 'Use Global Forms REST URL' box.

The Global Forms REST URL option allows you to have a single global URL that can be reused for multiple forms. This option is configured in the organization setup page that can be found using the navigation menu. Click Organization Setup, and scroll to the advanced options.

6. At this stage, your connector is ready to go. Click 'Save' to activate the connector.


Customize the request body

The 'customize body' option allows you to set up your own custom JSON or XML data payloads and inject form answer values using our standard #{{fieldname}} syntax.

You can even cater to repeating data in your body using our #{{!REPEATSTART}} #{{!REPEATEND}} syntax normally reserved for data templates.

For example, you might have a JSON body that repeats timesheet rows like this:

{
'timeEntries':
[
#{{!REPEATSTART}}
{
'entryDate':'#{{entryDate}}',
'startTime':''#{{startTime}}',
'finishTime':''#{{finishTime}}',
'timeTotal':#{{timeTotal}},
'description':'#{{entryDescription}}'
},
#{{!REPEATEND}}
],
'entryCount':#{{hiddenEntryCount}},
'headerSummary':'#{{headerSummary}}',
'entrySummary':'#{{entrySummary}}'
}


Set up a dynamic request URL

You can also inject answer values to dynamically build up the url that the request will be sent to. For example your target URL could look like:

http://somewhere.com/service/#{{myfield}}/contact?option=#{{myoption}}

Click on the hammer icon next to the Destination URL box.

Add custom HTTP headers

Use the 'customize headers' option to add HTTP request headers onto the REST request that is sent out by the platform. This is useful for external API services that require you to authenticate using 'Auth headers' that contain your username/password combinations. Header values can be dynamic as well, you can inject form field values using the usual #{{myfieldname}} syntax.

Note: HTTP Headers are NOT a way to send your form field names to the target API. Research HTTP headers to understand what these are and how to use them.


Add a run condition

You may have a connector that you only want to fire in the event that the form entry has a given answer value. For example you have an audit form, which has a risk rating question with options like 'Low', 'Medium' and 'High'. If the user answers the risk rating as 'High', then you want an email to be sent to a supervisor for follow up and action.

This is where a run condition comes in. Run conditions are defined by creating a true/false formula. The connector will only run if the formula you define in the run condition has a true result. In the example above, the run condition formula would be something like:

###{{riskRating}} = 'High'

When you hover over the run condition field, you will see a hammer icon appear. Clicking the hammer icon will take you into the formula builder, which helps you to create the formula you desire.

See the Creating a formula article to learn more about form formulas.

Did this answer your question?