Workflows

A workflow defines what happens automatically when a form event occurs — such as sending a confirmation email when a submission arrives, or posting to a Slack channel when a specific answer is submitted. Each workflow has a trigger that specifies when it fires and an ordered list of actions to execute.

List workflows

GET /workflows Returns a paginated list of workflows in your account.

Query parameters

integer

default:"20"

Number of workflows to return per page. Maximum 100.

string

Pagination cursor from a previous response’s next_cursor.

string

Filter to workflows that are attached to a specific form.

Response

object[]

Array of workflow objects.

Show Workflow object properties

string

Unique workflow identifier, prefixed with wfl_.

string

Display name of the workflow.

string

The form this workflow is attached to.

boolean

Whether the workflow is currently active.

object

The event that starts the workflow.

object[]

Ordered list of actions to execute.

string

ISO 8601 creation timestamp.

string

ISO 8601 timestamp of the last update.

string

Cursor for the next page. null on the last page.

boolean

true if more workflows exist beyond this page.

curl --request GET \
  --url "https://api.formflows.ai/v1/workflows?form_id=frm_8kQmP2xNvL" \
  --header "Authorization: Bearer sk_live_your_api_key"

import requests

response = requests.get(
    "https://api.formflows.ai/v1/workflows",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    params={"form_id": "frm_8kQmP2xNvL"},
)

result = response.json()
for wf in result["data"]:
    status = "enabled" if wf["enabled"] else "disabled"
    print(f"{wf['name']} ({status})")

Create a workflow

POST /workflows Creates a new workflow attached to a form.

Body parameters

string

required

Display name for the workflow.

string

required

The ID of the form that this workflow is attached to.

object

required

Defines the event that starts the workflow.

Show Trigger properties

string

required

The trigger event type. Supported values: submission.created, submission.updated.

object

Optional configuration for the trigger. For example, filter conditions that must match before the workflow fires.

Show Config properties

object[]

Array of conditions. Each condition has a field_id, operator (equals, not_equals, contains, greater_than, less_than), and value. All conditions must match for the workflow to fire.

object[]

required

Ordered list of actions to execute when the trigger fires.

Show Action properties

string

required

Action type. Supported values: send_email, send_webhook, slack_message, google_sheets_append.

object

required

Action-specific configuration. See action type reference below.

Action type reference

send_email

Sends an email when the workflow fires.

Config key	Type	Required	Description
`to`	string	Yes	Recipient email. Supports `{{field_id}}` template variables.
`subject`	string	Yes	Email subject line. Supports template variables.
`body`	string	Yes	Email body in plain text or HTML. Supports template variables.
`from_name`	string	No	Sender display name. Defaults to your account name.

send_webhook

Sends an HTTP POST request to a URL with the submission data as the body.

Config key	Type	Required	Description
`url`	string	Yes	Destination URL. Must use HTTPS.
`headers`	object	No	Additional HTTP headers to include.

slack_message

Posts a message to a Slack channel. Requires a connected Slack integration.

Config key	Type	Required	Description
`channel`	string	Yes	Slack channel ID or name (e.g., `#sales-leads`).
`message`	string	Yes	Message text. Supports template variables.

google_sheets_append

Appends a new row to a Google Sheet. Requires a connected Google integration.

Config key	Type	Required	Description
`spreadsheet_id`	string	Yes	Google Sheets spreadsheet ID.
`sheet_name`	string	Yes	Tab name within the spreadsheet.
`row_mapping`	object	Yes	Map of column headers to field IDs or static values.

Response

Returns the created workflow object with a 201 Created status.

curl --request POST \
  --url "https://api.formflows.ai/v1/workflows" \
  --header "Authorization: Bearer sk_live_your_api_key" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New registration — email confirmation",
    "form_id": "frm_8kQmP2xNvL",
    "trigger": {
      "type": "submission.created"
    },
    "actions": [
      {
        "type": "send_email",
        "config": {
          "to": "{{fld_e5F6g7H8}}",
          "subject": "You are registered for the 2025 Annual Conference",
          "body": "Hi {{fld_a1B2c3D4}},\n\nThank you for registering. We look forward to seeing you!\n\nThe Events Team"
        }
      },
      {
        "type": "slack_message",
        "config": {
          "channel": "#event-registrations",
          "message": "New registration from {{fld_a1B2c3D4}} ({{fld_e5F6g7H8}})"
        }
      }
    ]
  }'

import requests

payload = {
    "name": "New registration — email confirmation",
    "form_id": "frm_8kQmP2xNvL",
    "trigger": {
        "type": "submission.created",
    },
    "actions": [
        {
            "type": "send_email",
            "config": {
                "to": "{{fld_e5F6g7H8}}",
                "subject": "You are registered for the 2025 Annual Conference",
                "body": (
                    "Hi {{fld_a1B2c3D4}},\n\n"
                    "Thank you for registering. We look forward to seeing you!\n\n"
                    "The Events Team"
                ),
            },
        },
        {
            "type": "slack_message",
            "config": {
                "channel": "#event-registrations",
                "message": "New registration from {{fld_a1B2c3D4}} ({{fld_e5F6g7H8}})",
            },
        },
    ],
}

response = requests.post(
    "https://api.formflows.ai/v1/workflows",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    json=payload,
)

workflow = response.json()
print("Created workflow:", workflow["id"])

Example response:

{
  "id": "wfl_4nRsT6uVwX",
  "name": "New registration — email confirmation",
  "form_id": "frm_8kQmP2xNvL",
  "enabled": true,
  "trigger": {
    "type": "submission.created",
    "config": {}
  },
  "actions": [
    {
      "id": "act_yZ0aB1cD2e",
      "type": "send_email",
      "config": {
        "to": "{{fld_e5F6g7H8}}",
        "subject": "You are registered for the 2025 Annual Conference",
        "body": "Hi {{fld_a1B2c3D4}},\n\nThank you for registering. We look forward to seeing you!\n\nThe Events Team"
      }
    },
    {
      "id": "act_fG3hI4jK5l",
      "type": "slack_message",
      "config": {
        "channel": "#event-registrations",
        "message": "New registration from {{fld_a1B2c3D4}} ({{fld_e5F6g7H8}})"
      }
    }
  ],
  "created_at": "2025-01-15T11:30:00Z",
  "updated_at": "2025-01-15T11:30:00Z"
}

Get a workflow

GET /workflows/{id} Returns a single workflow by ID, including its full trigger and actions configuration.

Path parameters

string

required

The workflow ID, e.g. wfl_4nRsT6uVwX.

Response

Returns the full workflow object.

curl --request GET \
  --url "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX" \
  --header "Authorization: Bearer sk_live_your_api_key"

import requests

response = requests.get(
    "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
)

workflow = response.json()
print(f"Workflow '{workflow['name']}' has {len(workflow['actions'])} action(s).")

Update a workflow

PATCH /workflows/{id} Updates a workflow. Use this to enable or disable a workflow, rename it, or modify its trigger and actions. Only the fields you include are changed.

Path parameters

string

required

The workflow ID to update.

Body parameters

string

New display name.

boolean

Set to false to pause the workflow without deleting it. Set to true to re-enable it.

object

Replaces the workflow trigger configuration.

object[]

Replaces the entire actions array. Include existing action IDs to preserve them.

Response

Returns the updated workflow object.

curl --request PATCH \
  --url "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX" \
  --header "Authorization: Bearer sk_live_your_api_key" \
  --header "Content-Type: application/json" \
  --data '{"enabled": false}'

import requests

response = requests.patch(
    "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
    json={"enabled": False},
)

workflow = response.json()
print("Enabled:", workflow["enabled"])

Delete a workflow

DELETE /workflows/{id} Permanently deletes a workflow. In-progress executions are allowed to finish before the workflow is removed.

Path parameters

string

required

The workflow ID to delete.

Response

Returns a 204 No Content response on success.

curl --request DELETE \
  --url "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX" \
  --header "Authorization: Bearer sk_live_your_api_key"

import requests

response = requests.delete(
    "https://api.formflows.ai/v1/workflows/wfl_4nRsT6uVwX",
    headers={"Authorization": "Bearer sk_live_your_api_key"},
)

if response.status_code == 204:
    print("Workflow deleted.")

Overview

Endpoints

List workflows

Query parameters

Response

Create a workflow

Body parameters

Action type reference

Response

Get a workflow

Path parameters

Response

Update a workflow

Path parameters

Body parameters

Response

Delete a workflow

Path parameters

Response

​List workflows

​Query parameters

​Response

​Create a workflow

​Body parameters

​Action type reference

​Response

​Get a workflow

​Path parameters

​Response

​Update a workflow

​Path parameters

​Body parameters

​Response

​Delete a workflow

​Path parameters

​Response

List workflows

Query parameters

Response

Create a workflow

Body parameters

Action type reference

Response

Get a workflow

Path parameters

Response

Update a workflow

Path parameters

Body parameters

Response

Delete a workflow

Path parameters

Response