FormFlow AI API Documentation

Integrate the power of FormFlow AI into your applications and workflows. Access AI-driven form generation, response analysis, and automation capabilities.

Work in Progress

This documentation outlines conceptual APIs based on our current Genkit flows and planned features like n8n webhooks. Actual HTTP API endpoints with authentication and rate limiting are planned for future development. The n8n webhook integration described below is functional.

General Information

The FormFlow AI API provides access to core AI functionalities. All conceptual API endpoints accept JSON in the request body and return JSON.

For webhook integrations (like n8n), FormFlow AI sends data as a JSON payload to your configured URL.

Authentication (Future API Endpoints)

For production API access, an API key will be required. This key must be included in theAuthorization header as a Bearer token. (e.g., Authorization: Bearer YOUR_API_KEY). API keys are not yet available for self-service.

Rate Limits (Future API Endpoints)

Standard rate limits will apply to protect the service. Details will be provided upon API key issuance.

Error Handling (Future API Endpoints)

The API will use standard HTTP status codes to indicate success or failure. Error responses will be in JSON format and include a message field. For webhook calls, FormFlow AI logs errors internally if your endpoint fails to respond successfully (e.g., with a 2xx status code).

Workflow Automation with n8n

n8n Webhook Integration

Receive real-time notifications of new form submissions in your n8n workflows.

When a form is submitted, FormFlow AI can send a POST request to your specified n8n webhook URL with the submission data. This allows you to trigger custom workflows in your own n8n instance.

1. Setting up in FormFlow AI

In the Form Creator page, under the "n8n Workflow Automation" section (typically when editing/creating a form):

Enter the n8n Webhook URL (obtained from your n8n workflow's Webhook node) into the designated input field.
Toggle the "Enable n8n Webhook" switch to activate the integration for that specific form.
Save/Publish your form.

2. Setting up your n8n Workflow

In your n8n instance:

Create a new workflow or open an existing one.
Add a "Webhook" node. This will be your trigger.
In the Webhook node settings:
- The "HTTP Method" should be set to POST.
- Copy the "Test URL" or "Production URL" provided by n8n. This is the URL you paste into FormFlow AI.
- When you first set it up, n8n will wait for test data. You can submit your FormFlow AI form once to send data and help n8n detect the structure.
Connect other nodes (e.g., "Set", "Google Sheets", "Slack", "Email") to process the incoming data from FormFlow AI.

Visit n8n.io

3. Webhook Payload Structure

FormFlow AI will send the following JSON payload to your n8n webhook:

{
  "formId": "frm_abc123",
  "formTitle": "Customer Feedback Form",
  "submissionId": "sub_def456",
  "clientSubmittedAt": "2024-05-15T10:30:00.123Z",
  "answers": {
    "question_id_1": "Answer for Q1",
    "question_id_2": "Answer for Q2"
  },
  "prettyAnswers": {
    "What is your name?": "John Doe",
    "Your Feedback": "Great service!"
  }
}

formId: (string) The unique ID of the FormFlow AI form.
formTitle: (string) The title of the form (English version for consistency).
submissionId: (string) The unique ID of this specific submission.
clientSubmittedAt: (string) ISO 8601 timestamp of when the submission was made by the client.
answers: (object) Key-value pairs of raw answers, where keys are question IDs. File uploads will be represented as metadata objects (e.g., { name: "file.pdf", type: "application/pdf", size: 12345 }).
prettyAnswers: (object) Key-value pairs where keys are the question texts (English version) and values are the answers. This can be more convenient for direct use in some n8n nodes.

4. Example n8n Workflow (Basic)

This basic workflow logs data and sends a Slack message if feedback contains "urgent". You can import this JSON into your n8n instance.

{
  "nodes": [
    {
      "parameters": {},
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [
        440,
        300
      ],
      "webhookId": "YOUR_N8N_WEBHOOK_ID_HERE"
    },
    {
      "parameters": {
        "options": {}
      },
      "name": "Log Data (Optional)",
      "type": "n8n-nodes-base.noOp",
      "typeVersion": 1,
      "position": [
        660,
        300
      ]
    },
    {
      "parameters": {
        "conditions": {
          "options": {},
          "conditions": [
            {
              "value1": "={{$json.body.prettyAnswers['Your Feedback']}}",
              "operation": "contains",
              "value2": "urgent"
            }
          ]
        },
        "options": {}
      },
      "name": "If Urgent Feedback",
      "type": "n8n-nodes-base.if",
      "typeVersion": 1,
      "position": [
        660,
        500
      ]
    },
    {
      "parameters": {
        "channel": "#feedback",
        "text": "=Form Submission: {{$json.body.formTitle}}\nID: {{$json.body.submissionId}}\nUrgent: {{$json.body.prettyAnswers['Your Feedback']}}",
        "otherOptions": {
          "options": {}
        },
        "authentication": "slackApi",
        "slackApi": {
          "id": "YOUR_SLACK_CREDENTIAL_ID",
          "name": "Slack account"
        }
      },
      "name": "Send to Slack",
      "type": "n8n-nodes-base.slack",
      "typeVersion": 1,
      "position": [
        880,
        500
      ]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Log Data (Optional)",
            "type": "main",
            "index": 0
          },
          {
            "node": "If Urgent Feedback",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "If Urgent Feedback": {
      "main": [
        [
          {
            "node": "Send to Slack",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Remember to replace placeholder credential IDs and webhook IDs in n8n after importing.

Webhook Node: Triggers on FormFlow AI submissions.
Log Data (NoOp): Placeholder for logging/debugging.
If Node: Checks if prettyAnswers['Your Feedback'] contains "urgent".
Slack Node: If true, sends a message to Slack (configure credentials).

Common n8n Workflow Recipes

Conceptual guides for automating common tasks with FormFlow AI and n8n.

Send Data to Google Sheets

Automatically add new form submissions as rows in a Google Sheet.

Nodes: Webhook (Trigger) → Google Sheets.
Webhook Node: Configure as per FormFlow AI setup.
Google Sheets Node:
- Authentication: Connect your Google account.
- Resource: Spreadsheet, Operation: Append Row.
- Spreadsheet ID & Sheet Name: Specify your target sheet.
- Fields: Map data from FormFlow AI. Example for a column "Name": ={{$json.body.prettyAnswers['Your Name']}}. Map other fields similarly.

Send Email Notification (Gmail)

Send a customized email for each new form submission.

Nodes: Webhook (Trigger) → Gmail.
Webhook Node: Standard setup.
Gmail Node:
- Authentication: Connect your Gmail account.
- Resource: Message, Operation: Send.
- To, Subject, Body: Use expressions to include form data, e.g., Subject: New submission for {{$json.body.formTitle}}. Body: Name: {{$json.body.prettyAnswers['Name']}}, Email: {{$json.body.prettyAnswers['Email']}}.

Create Task in Project Manager (e.g., Trello/Asana concept)

Create a new task or item in your project management tool from a form submission.

Nodes: Webhook (Trigger) → [Your Tool's Node, e.g., Trello, Asana].
Webhook Node: Standard setup.
Tool Node (e.g., Trello):
- Authentication: Connect your Trello/Asana account.
- Resource: Card/Task, Operation: Create.
- Board/List/Project: Select where to create the task.
- Name/Title: Map form data, e.g., New Inquiry from {{$json.body.prettyAnswers['Name']}}.
- Description: Include more details from prettyAnswers.
Note: Specific fields and operations vary by tool. Consult the n8n documentation for your chosen project management tool.

These are conceptual guides. You'll need to adapt them to your specific n8n setup and the fields in your FormFlow AI forms. Always refer to the official n8n documentation for node-specific configurations and authentication.

Other Third-Party Integrations (Future)

Connect FormFlow AI to thousands of other apps using platforms like Zapier, Make.com, or Pabbly Connect.

While direct n8n integration is the current focus, future development may include dedicated connectors for other platforms or enhanced generic webhook capabilities.

Common Use Cases:

Send an email notification via Gmail for each new submission.
Add new responses as rows in a Google Sheet.
Create a new task in Notion or Asana from a form entry.
Add contacts to your CRM (e.g., HubSpot, Salesforce).

Status: Under consideration for future development. n8n is the primary method for this type of automation currently.

Conceptual Genkit AI Endpoints

POST /api/v1/generate-form

Generates a form JSON structure from a natural language prompt.

Request Parameters

Name	Type	Description	Required
userPrompt	string	Natural language description of the form to create.	Yes

Response Parameters

Name	Type	Description	Required
formJsonString	string	A JSON string representing an array of Question objects for the form.	No

Example Request

{
  "userPrompt": "A customer feedback form for a coffee shop with rating and comments."
}

Example Response

{
  "formJsonString": "[\n  {\n    \"id\": \"rating\",\n    \"type\": \"radio\",\n    \"text\": {\n      \"en\": \"How was your experience?\"\n    },\n    \"options\": [\n      {\n        \"value\": \"5\",\n        \"label\": {\n          \"en\": \"Excellent\"\n        }\n      }\n    ],\n    \"isRequired\": true\n  },\n  {\n    \"id\": \"comments\",\n    \"type\": \"textarea\",\n    \"text\": {\n      \"en\": \"Any comments?\"\n    },\n    \"isRequired\": false\n  }\n]"
}

POST /api/v1/summarize-responses

Summarizes a collection of form responses, providing insights, key themes, and suggested actions.

Request Parameters

Name	Type	Description	Required
formTitle	string	The title of the form for which responses are being summarized.	Yes
responses	array<object>	An array of form responses.	Yes
responses[].submittedAt	string (ISO Date)	Timestamp of submission.	No
responses[].answers	object (questionId: answerValue)	Key-value pairs of answers.	No
questionMap	object (questionId: questionText)	Optional map of question IDs to question texts for better context.	No

Response Parameters

Name	Type	Description	Required
summary	string	Concise summary of responses, highlighting key insights and trends.	No
keyThemes	array<string>	Up to 3 key themes identified.	No
suggestedActions	array<string>	1-2 high-level actionable insights.	No

Example Request

{
  "formTitle": "Coffee Shop Feedback",
  "responses": [
    {
      "submittedAt": "2024-05-01T10:00:00Z",
      "answers": {
        "rating": "5",
        "comments": "Loved the new blend!"
      }
    },
    {
      "submittedAt": "2024-05-01T11:00:00Z",
      "answers": {
        "rating": "4",
        "comments": "Good, but a bit crowded."
      }
    }
  ],
  "questionMap": {
    "rating": "How was your experience?",
    "comments": "Any comments?"
  }
}

Example Response

{
  "summary": "Overall, customers seem pleased with their experience, particularly noting enjoyment of new coffee blends. Some feedback mentioned crowding as a minor issue.",
  "keyThemes": [
    "Positive Coffee Experience",
    "Store Ambiance/Crowding"
  ],
  "suggestedActions": [
    "Continue promoting new coffee blends.",
    "Explore options to manage peak hour crowding."
  ]
}

POST /api/v1/analyze-response

Analyzes a single form submission to provide detailed insights, suggested replies, urgency, and sentiment.

Request Parameters

Name	Type	Description	Required
formTitle	string	The title of the form for overall context.	Yes
questionDetails	array<object>	Array of question objects (id, text, type) from the form definition.	Yes
questionDetails[].id	string	Question ID.	No
questionDetails[].text	string	Main text of the question.	No
questionDetails[].type	string	Type of the question.	No
responseAnswers	object (questionId: answerValue)	User's answers.	Yes
responseSubmittedAt	string (ISO Date)	Timestamp of response submission.	Yes

Response Parameters

Name	Type	Description	Required
summary	string	Concise summary (1-2 sentences) of this specific response.	No
keyPoints	array<string>	Array of 2-3 bullet points highlighting the most important information.	No
suggestedReply	string (optional)	If applicable, a brief, polite, and relevant suggested reply.	No
urgency	enum ("low", "medium", "high", "none")	Urgency level for follow-up.	No
sentiment	enum ("positive", "negative", "neutral", "mixed", optional)	Overall sentiment expressed.	No

Example Request

{
  "formTitle": "Customer Satisfaction Survey",
  "questionDetails": [
    {
      "id": "q1",
      "text": "Overall satisfaction?",
      "type": "radio"
    },
    {
      "id": "q2",
      "text": "Comments?",
      "type": "textarea"
    }
  ],
  "responseAnswers": {
    "q1": "negative",
    "q2": "The service was very slow today."
  },
  "responseSubmittedAt": "2024-05-03T14:30:00Z"
}

Example Response

{
  "summary": "User expressed dissatisfaction due to slow service.",
  "keyPoints": [
    "Negative overall satisfaction.",
    "Specific complaint about slow service."
  ],
  "suggestedReply": "We sincerely apologize for the slow service you experienced. We are looking into this to ensure it doesn't happen again. Thank you for your feedback.",
  "urgency": "high",
  "sentiment": "negative"
}

POST /api/v1/analyze-sentiment

Analyzes text to determine sentiment and suggest a relevant emoji.

Request Parameters

Name	Type	Description	Required
textToAnalyze	string	The text whose sentiment needs to be analyzed.	Yes

Response Parameters

Name	Type	Description	Required
sentiment	enum ("positive", "negative", "neutral")	The classified sentiment.	No
emoji	string	A single emoji character representing the sentiment.	No

Example Request

{
  "textToAnalyze": "This is a wonderful product!"
}

Example Response

{
  "sentiment": "positive",
  "emoji": "😃"
}

POST /api/v1/translate-form

Translates a form definition (JSON string) into a target language.

Request Parameters

Name	Type	Description	Required
formDefinition	string	The JSON definition of the form to translate.	Yes
targetLanguage	string	The ISO code of the target language (e.g., "es").	Yes

Response Parameters

Name	Type	Description	Required
translatedFormDefinition	string	The JSON definition of the translated form.	No

Example Request

{
  "formDefinition": "[{\"id\":\"name\",\"type\":\"text\",\"text\":{\"en\":\"Your Name\"}}]",
  "targetLanguage": "es"
}

Example Response

{
  "translatedFormDefinition": "[{\"id\":\"name\",\"type\":\"text\",\"text\":{\"es\":\"Tu Nombre\"}}]"
}