- Basic Set Up
- Request/Response Configuration
- Request Headers
- Request Body
- Testing and Troubleshooting
The HTTP POST/PUT/PATCH Data Destination can send any form submission data to any web app or data storage service accessible through the internet. This makes it an ideal deal for low-code custom integrations.
This destination can send raw data (including files & photos) from submitted forms to an external system, or create or update objects in other systems.
Data destinations automatically send data collected in the field. They reduce the need to visit the web portal by making submitted forms available through the services you already use. The information from your submitted form can be routed to different places: the customer can receive a finished form, and the data from that form can be sent to back-office systems seamlessly. Read here for more information on data destinations.
- Create the data destination following the instructions here.
- Set up the Request/Response Configuration tab as discussed below.
When you are communicating with another system, this is the content of that communication.
- The Request is what ProntoForms sends to the other system; it contains information about what action you would like to do in that system (like create a record) and what information it should be updated with (typically, the answers to your form questions). The requirements vary depending on the system you are connecting to, and what you would like to do in it.
- The Response is what the other system sends back to ProntoForms; it contains the status of the request (if it was successful or not), information about what happened, and error codes if it didn't work. The response will vary depending on the system you are connecting to.
ProntoForms supports PATCH, POST, and PUT HTTP methods.
- POST: POST uses data from a submitted form to create an object in an external system.
- PUT: PUT uses data from a submitted form to replace an existing object in an external system.
- PATCH: PATCH uses data from a submitted form to update or modify an object in an external system
An object may be as simple as a line of data in a database.
Which method should I use?
If you're using a system with a publicly documented API, the documentation should tell you which method you need to use for the request you are trying to make.
Some external systems require you to send additional headers in your request. These provide the system with additional required information that it needs in order to understand your request body.
For example, here is the API documentation for a 3rd-party system. Note the two -H lines; these are required headers.
Building Request Headers
Key: The name of the header
Value Expression: The value. This can be static. If this needs to be dynamic, and based on the answer to question, use Data Record Expression Language to choose the data to send. Use the answer to a question by referencing Unique IDs.
Common Request Headers
- Authorization: For systems that only provide an Authentication token, often they specify that this must be sent as a header.
- Content-Type: Many systems require this. It tells the external system what data format they should expect the response body in.
The Request Body specifies the actual data you will be sending through the data destination. This is usually what contains the actual answers from your form.
There are two methods to define a Request Body:
- POST Parameters (only available for the POST method)
- A separate JSON or XML file containing the Request Body
Only use these options if you are NOT sending a separate JSON or XML file containing the request body. All of these parameters will be ignored if you attach a document.
When used, these parameters will be sent in the request body in a url-encoded format.
Send all answers
If using POST, selecting this option will automatically add all of the submission's answers to the POST request. This eliminates the need to reference questions individually in the "POST Parameters" section below.
These parameters are only displayed when using the POST method. Use the parameter builder to choose which individual answers to send.
- Key: The name of the POST parameter that the destination will use.
- Value Expression: Use Data Record Expression Language to choose the data to send. Use the answer to a question by referencing unique IDs.
- Note: Answer values which are binary data (e.g. data from an image capture or signature) are base64 encoded.
When this option is selected, the information from answered questions will be sent in an legacy format, using the unique identifier for each answer. This format will send all data as a comma separated string instead of a list of HTTP POST parameters. This option is not recommended for forms containing:
- Attachment data
- Barcode data
- Multiselect questions
- Repeatable sections
In many cases, a JSON or XML document is required by the web end point you are communicating with.
Note: For PUT/PATCH, you must use this method of defining the request body. For POST, you may need to use this, depending on the requirements of the system you are sending data to.
ProntoForms has several features that enable this:
- Standard JSON or XML formats, which include every quest/answer in ProntoForms' standard data format
- Create your own custom JSON or XML formats through DREL,Freemarker, or Handlebars document template features; include only specific questions, write conditions, and exactly match the data format required by the system you are connecting to
To make use of one of these document generation options with an HTTP destination, follow the instructions to Link a document to a data destination.
Select which HTTP response codes indicate a successful call. Optionally, you can use a Regular Expression to analyze the HTTP response body to determine success vs. failure. The Regular Expression results in success if the pattern is found anywhere in the body.
Response Data Handling / Response Outputs
HTTP POST/PUT Destinations allow storing and use of the HTTP Response for use with DREL. For more information on Destination Response Outputs, please read the documentation: Destination Response Outputs.
Data destinations should be configured and tested carefully before using them in production. This is key to ensuring that ProntoForms data is received correctly. Please consult the recommendations for testing and troubleshooting data destinations.
Keep in mind when building a custom integration that ProntoForms technical support may have no experience with the system you are integrating with. Most error codes that you see come back to ProntoForms from that other system; ProntoForms is just surfacing the message back to you.
If you are working with a documented API, refer to that documentation to learn what various error codes mean.