API Connectors

API Connectors turn HTTP endpoints into reusable FormWork workflow actions. A connector belongs to a project; its action definitions are shared across its Sandbox, Test, or Live environments.

Create a Connector

1. Open a project and select Extensions.
2. Under API Connectors, select Create.
3. Enter a Connector name and Connector ID.
4. Select Create connector.

The connector ID is a lowercase slug and cannot be changed after creation. You can create an empty connector and add environments and actions next, or start with Import OpenAPI.

Import OpenAPI

The import flow accepts OpenAPI YAML or JSON in three ways:

• Paste the specification.
• Upload a file.
• Provide a specification URL.

Select Preview operations, review supported and unsupported operations, and choose the supported ones to import. You can search, filter by support status or HTTP method, and select or clear all visible supported operations before creating the connector or adding actions. A single import supports up to 100 actions.

Review generated parameter and response schemas after import. An OpenAPI document is a useful starting point, but descriptions and schemas may still need adjustment for a clear workflow mapping experience.

Define Actions

An action describes one HTTP operation. Select Add action, then configure:

• Action name and optional description
• Method, encoding, and path
• Path, query, and header parameters
• Optional request body schema
• Optional response schema
• Whether that endpoint bypasses environment authentication

You can build request and response schemas from example JSON or OpenAPI, or define the endpoint and fields manually. Save an action before testing if you want its test history to persist.

Actions belong to the connector definition, not to one environment. Editing an action changes it for every environment that uses the connector.

Action control reference

• Method: GET, POST, PUT, PATCH, or DELETE.
• Encoding: json or form; this action setting determines how its body is sent.
• Path: begins with / and may contain placeholders such as /contacts/{id}. FormWork detects each brace placeholder as a required path parameter.
• Bypass auth for this endpoint: sends this action without the environment credential; default is to inherit environment authentication.
• Query params and Header params: each has a name, type (string, number, boolean, or object), Required switch, and workflow-facing description.
• Request schema: available for non-GET actions and becomes the workflow’s body-mapping contract.
• Response schema: describes JSON response fields exposed beneath parsed_body.

For either schema, choose JSON example or OpenAPI spec, then validate and preview the result before applying it to the action draft. The preview can show a visual tree or raw specification. OpenAPI input can be pasted or uploaded, can identify an operation by ID, and can optionally update the action’s method, path, and parameters when applied. You can also clear either schema.

The Workflow output tab summarises every workflow-visible input and response field. Saved actions can be duplicated or deleted; deletion cannot be undone and may break workflow steps that use that action ID.

Add an Environment

Each environment has its own:

• Environment name and immutable lowercase Environment ID
• Enabled and default state
• Base URL
• Default json or form encoding
• Request timeout in seconds
• Authentication and secret
• Default headers

New environments start disabled. The first environment becomes the default; you can make another environment the default later. An enabled environment requires a base URL.

You can edit the environment name, enabled state, URL, encoding, timeout, authentication, secret replacement, and headers. The environment ID cannot be changed. You can also make an environment default or delete it; workflows using a deleted environment must be reconfigured.

Authentication

Supported authentication types are:

Default headers apply to every action in that environment. Action-specific mapped headers can add to or override the request as configured.

Test an Action

Open a saved action’s test area and:

1. Choose an enabled Environment.
2. Enter path, query, header, and body values as JSON.
3. Select Preview request for a dry run that resolves the request without sending it.
4. Select Send test to make the request.
5. Inspect the request, response status, headers, body, duration, and error details.

Saved test runs appear in History. Select a run to inspect it again or delete it when it is no longer useful.

Use an Action in a Workflow

1. Add or edit a workflow on a draft form version.
2. Select + Add Step.
3. Choose the API Connector by name and select an enabled environment and action.
4. Map entry values and previous workflow outputs into the action’s request fields.
5. Connect Next and, when needed, Error.
6. Publish the form version and test the real trigger with a test entry.

If the selected environment is disabled or the action is deleted, the connector action cannot be added or run until the workflow is reconfigured.

Response Outputs

Downstream steps use the normal workflow reference syntax:

workflow:current.steps.<step-id>.outputs.status_code
workflow:current.steps.<step-id>.outputs.headers
workflow:current.steps.<step-id>.outputs.raw_body
workflow:current.steps.<step-id>.outputs.parsed_body
workflow:current.steps.<step-id>.outputs.parsed_body.<field>

Available outputs are:

A response schema lets the reference picker expose fields beneath parsed_body. Without a parseable JSON body, parsed_body is absent.

Success, HTTP Errors, and Failures

When the HTTP request completes:

• A success status follows Next.
• A non-2xx status follows Error, where you can inspect the response outputs.

Failures before a completed response—such as an invalid reference, missing environment configuration, blocked URL, timeout, DNS failure, or connection failure—fail the workflow run. They do not follow the Error path.

Security and Network Rules

Saved authentication secrets are not exposed to respondents or included in form data. API Connectors can call public web APIs; private, loopback, link-local, and other restricted network destinations are not supported. Redirected requests follow the same safety rules.

API Connectors are declarative HTTP definitions. They cannot upload or execute custom code, add native extension fields, or register inbound webhook hooks.

Troubleshooting

• Confirm the environment is enabled and has a valid base URL.
• Confirm the action path does not duplicate part of the base URL.
• Check the authentication placement and replace the stored secret if needed.
• Use Preview request to inspect URL, headers, and body before sending.
• Add or correct the response schema when parsed_body fields do not appear in the reference picker.
• Inspect connector test history for action-level problems and Workflow Runs for mapping or path problems.