The API Connector will allow you to prefill workflow steps with information from third party systems. This will encourage an easy flow of information between Formstack and other systems, helping ensure that your information is always up to date.
Article Contents:
Who has access to this feature?
Where can an API Connector be placed?
Who has access to this feature?
Any account that is on a Suite and Suite Teams+ plan, as well as if you've purchased the Workflows Pro Add-on. Please contact our sales team If you're interested in hearing more about purchasing this Add-on.
Where can an API Connector be placed?
-
-
As the first step in a workflow – prefilling static values only.
-
Example: If you want your third party system to be informed that a workflow has started. When implemented, we let the third party know that the workflow has begun. This could be setup to be able to receive a submission ID when a workflow starts, and once it does, Formstack receives a payload that includes static values that can be mapped to additional steps in the workflow.
-
-
After a forms step (after first step in Workflow) – preflling static and dynamic values.
-
Example: a patient enters their Medical ID# and DOB in a form, submits, the 3rd party API is called, and a new form loads with prefilled information
-
-
Before/After a Docs or Sign step
-
Use case/Example: Generating a document with information from a third party system.
-
-
-
HTTP Requests include:
-
Prefill workflow steps (GET)
-
Delete information in 3rd party system (DELETE)
-
-
Mapping prefilled information
-
Information that is pulled (via GET request) into Formstack can be mapped to future workflow steps, just like other information that currently can be mapped in Workflows.
-
How to set it up
Drag and drop the API connector into your workflow from the left utilities sections, please see the previous section if you'd like to review where you can place the connector with examples of why for each scenario.
Example of first step
Example of after first step
Click the "Configure API" option on the Workflow step and you'll be taken to the "Connector details" page. On this page, you can name your connector and add a description that others in your organization would find helpful. Once finished, you can click next on the top right to continue to the HTTP Request page.
On the HTTP Request page, you'll want to start with the credentials you'd be potentially using for this connector with the options: Basic, Bearer or None. Here are a few examples of which ones you might use:
Basic Authentication - This involves sending a username and password encoded in Base64 as part of the HTTP request headers. Just provide a username and password that are sent with each request to verify your identity.
Bearer Authentication - Bearer Authentication uses a token, typically a string of characters, which is included in the HTTP request headers. This token is usually obtained after logging in and is used for accessing resources without repeatedly entering login credentials.
No Authentication - No Authentication means that the API does not require any credentials or tokens to access its resources. All requests are open and can be made without verifying the user's identity.
After you've chosen the type of credentials you'd be using for this connector, the next step is choosing the type of HTTP request and adding the API url that would be used for this request. Please note the types of HTTP requests include:
- Prefill workflow steps (GET)
- Delete information in 3rd party system (DELETE)
Example with URL
After the API URL is added and the type of HTTP request has been chosen, the next step is reviewing/setting the Query Parameters. This data will be sent to your API to verify the information provided by your workflow users. Parameters are additional details added to a web address (URL) to give more information to a web server when making requests.
Note: The API url forms the base endpoint to which the query parameters are appended. Query parameters refine the request, but they do not replace the need for the base URL.
It's worth mentioning that we support path parameters. In your URL, use : to mark your parameter. For example: https://examplerequest.com/:exampleParam. This will then auto-populate a table below where you can make any adjustments. In this case, exampleParam is your key. You can then map the value or have it static
After you've entered the parameters.
After you've entered the parameters, there's the option right below to test the request and get results in the response payload at the bottom of this page.
Important Note: This is the information that will be returned from the HTTP request and what will be able to be mapped in Workflow steps.
After you're happy with the results of your test, you'll want to make sure to click Done on the top right to finish setting up the connector.
Frequently asked questions
Are there any limitations on Form field types?
All field types are supported - Formstack can pull data from all field types via the API connector details.
How can I be sure that we are prefilling workflow data in a step that is actually intended to be seen by the person accessing the step. What safeguards do Formstack have in place to guard against bad actors?
Formstacks Query parameters will allow you to set up the connector so that workflow steps will only be prefilled if information provided by the end user in a prior workflow step matches what is in the third party system of record. Think a student ID or medical ID as examples.
Does this support Forms SSO prefil?
Users can configure this in forms – end users will be able to authenticate as well as view information prefilled in the 1st step. Please see this article for more information.
Can a API Connector step be skipped with step logic?
Similar to Approvals, an API Connector step cannot be skipped with Step Logic
What types of authentication are not supported?
We do not support Oauth or Oauth 2.0 at this time
What user actions are available for only 60 days when an API Connector is part of a Workflow?
Once a third party system is called via API, the information we receive will be stored via cache for 60 days. For 60 days, users are able to map fields with values provided via the API to future workflow steps (aka, future workflow steps will be successfully prefilled for 60 days). Once that 60 days is exceeded, the workflow will have to begin again from the API connector step (aka, the API will need to be called again via the connector).