# Formfex Developer Documentation — Full Reference
> Complete REST API, n8n Integration, Webhooks, and Smart Forms Developer Reference

This document provides a comprehensive technical reference for developers, AI agents, and automation platforms integrating with Formfex. For a summary, see https://docs.formfex.com/llms.txt

For product-level information about Formfex, see https://formfex.com/llms.txt


## 1. Overview

Formfex is an AI-powered form platform with a full Public REST API. The API enables:

- Creating and managing forms programmatically (9 field types, conditional logic, validation rules)
- Creating AI Smart Forms (conversational AI interviews that generate questions dynamically)
- Collecting and querying form responses
- Triggering AI-powered analytics and natural language Q&A on response data
- Managing webhooks for real-time event notifications
- Automating workflows via the native n8n community node

Base URL: https://api.formfex.com/api/v1/public
All endpoints return JSON. All requests require API key authentication.


## 2. Authentication

### API Key Format

API keys follow the format: fxk_live_<keyId>.<secret>

- Prefix: fxk_live_ (9 chars)
- Key ID: 12 hex chars (random identifier)
- Separator: .
- Secret: 64 hex chars (256-bit random)

Example: fxk_live_a1b2c3d4e5f6.abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789

### Making Requests

Include the API key in the Authorization header as a Bearer token:

curl -X GET "https://api.formfex.com/api/v1/public/forms" \
  -H "Authorization: Bearer fxk_live_<your-key>"

### API Key Scopes

Each key has granular scopes:

| Scope | Access |
|-------|--------|
| FORMS_READ | List and read forms |
| FORMS_WRITE | Create, update, delete, publish/unpublish forms |
| RESPONSES_READ | Read form responses and counts |
| WEBHOOKS_READ | List webhooks |
| WEBHOOKS_WRITE | Create, update, delete webhooks |
| AI_GENERATE | AI form generation and job polling |
| ANALYTICS_READ | Smart analytics and analytics chat |
| SMART_FORMS_READ | List and read smart forms and sessions |
| SMART_FORMS_WRITE | Create, update, delete, publish/unpublish smart forms |

### API Keys Per Plan

| Plan | Max Keys |
|------|----------|
| Free | 0 (no API access) |
| Starter ($9/mo) | 3 |
| Pro ($29/mo) | 10 |
| Max ($120/mo) | 25 |

### Key Rotation

Keys can be rotated with a grace period (default 24h, max 7 days). Both old and new keys work during the grace period. After expiry, the old key is deactivated automatically.

### Security Best Practices

- Never expose keys in client-side code — server-to-server only
- Use minimum required scopes
- Set expiry dates for temporary integrations
- Rotate keys regularly
- Revoke unused keys promptly


## 3. Response Format

All API responses use a consistent envelope:

{
  "message": "Human-readable status message",
  "data": { ... },
  "error": null
}

Error responses:

{
  "message": "Error description",
  "data": null,
  "error": "ERROR_CODE"
}


## 4. Rate Limits

### Limits by Plan

| Plan | Per Minute | Per Hour | Monthly Quota |
|------|-----------|----------|---------------|
| Starter | 20 | 200 | 2,000 |
| Pro | 60 | 1,000 | 20,000 |
| Max | 150 | 3,000 | 200,000 |

### AI Endpoint Limits (separate from general limits)

| Endpoint | Starter | Pro | Max |
|----------|---------|-----|-----|
| Generate Form | 10/hr | 30/hr | 100/hr |
| Smart Analytics | — | 5/hr | 20/hr |
| Analytics Chat | — | 30/hr | 100/hr |

### Rate Limit Headers

Every response includes:
- X-RateLimit-Limit: Hourly request limit
- X-RateLimit-Remaining: Remaining in current window
- X-RateLimit-Reset: Unix timestamp when window resets
- X-Monthly-Limit: Monthly quota
- X-Monthly-Used: Calls used this period
- X-Monthly-Reset: When monthly period resets

### 429 Response Body

Rate limit errors include a rate_limit object:

{
  "error": "TOO_MANY_REQUESTS",
  "rate_limit": {
    "type": "BURST_LIMIT | HOURLY_LIMIT | MONTHLY_QUOTA | AI_ENDPOINT_LIMIT",
    "retry_after": 45,
    "limit": 1000,
    "remaining": 0,
    "reset": 1710000000
  }
}


## 5. Forms API

### GET /forms — List Forms

Query parameters:
- page (number, default: 1)
- limit (number, 1-100, default: 20)
- search (string, case-insensitive title match)
- since (ISO 8601 timestamp, for incremental sync)

Response:
{
  "data": {
    "forms": [
      {
        "id": "uuid",
        "title": "Form Title",
        "description": "...",
        "publishStatus": "DRAFT | PUBLISHED | ARCHIVED",
        "publishVisibility": "PUBLIC | PRIVATE",
        "publishedAt": "ISO 8601 | null",
        "shareUrl": "aB3xK9mN2p | null",
        "expiresAt": "ISO 8601 | null",
        "updatedAt": "ISO 8601",
        "meta": { "title": "...", "language": "en" },
        "settings": { "layout": "single-column" }
      }
    ],
    "total": 24,
    "hasMore": true
  }
}

### GET /forms/:id — Get Form

Returns full form with schema, fields, sections, validation rules, and conditional logic.

### POST /forms — Create Form

Request body:
{
  "title": "Customer Feedback Survey",
  "schema": {
    "version": "1.0",
    "schemaVersion": "2026-02",
    "meta": {
      "title": "Customer Feedback Survey",
      "description": "Optional description",
      "language": "en",
      "submitLabel": "Submit"
    },
    "settings": {
      "layout": "single-column",
      "submitAction": "default"
    },
    "sections": [
      { "id": "section-1", "title": "Section Title", "order": 1 }
    ],
    "fields": [
      {
        "id": "field-1",
        "sectionId": "section-1",
        "type": "text",
        "label": "Your Name",
        "order": 1,
        "required": true,
        "validation": {
          "rules": [
            { "type": "required", "message": "Name is required" },
            { "type": "minLength", "value": 2 }
          ]
        }
      },
      {
        "id": "field-2",
        "sectionId": "section-1",
        "type": "select",
        "label": "Rating",
        "order": 2,
        "options": [
          { "label": "Good", "value": "good" },
          { "label": "Poor", "value": "poor" }
        ]
      },
      {
        "id": "field-3",
        "sectionId": "section-1",
        "type": "textarea",
        "label": "Details",
        "order": 3,
        "conditionalLogic": {
          "action": "show",
          "conditionGroups": [
            {
              "conditions": [
                { "fieldId": "field-2", "operator": "equals", "value": "poor" }
              ]
            }
          ]
        }
      }
    ]
  }
}

### Field Types

| Type | Description | Requires options |
|------|-------------|-----------------|
| text | Single-line text | No |
| textarea | Multi-line text | No |
| number | Numeric input | No |
| email | Email with validation | No |
| select | Dropdown selection | Yes |
| radio | Radio button group | Yes |
| checkbox | Checkbox group | Yes |
| date | Date picker | No |
| file | File upload | No (optional fileConfig) |

### Validation Rules

| Rule | Value Type | Description |
|------|-----------|-------------|
| required | — | Field must have a value |
| minLength | number | Minimum string length |
| maxLength | number | Maximum string length |
| min | number | Minimum numeric value |
| max | number | Maximum numeric value |
| pattern | string (regex) | Must match regex |

### Conditional Logic Operators

| Operator | Description | Requires value |
|----------|-------------|---------------|
| equals | Exact match | Yes |
| notEquals | Not equal | Yes |
| contains | String contains | Yes |
| notContains | String does not contain | Yes |
| startsWith | String starts with | Yes |
| endsWith | String ends with | Yes |
| greaterThan | Numeric > | Yes |
| lessThan | Numeric < | Yes |
| greaterThanOrEqual | Numeric >= | Yes |
| lessThanOrEqual | Numeric <= | Yes |
| before | Date before | Yes |
| after | Date after | Yes |
| isEmpty | No value | No |
| isNotEmpty | Has value | No |
| isChecked | Checked | No |
| isNotChecked | Not checked | No |

Conditions use AND/OR groups: conditions within a group are AND'd, groups are OR'd.

### PATCH /forms/:id — Update Form

Update title and/or schema.

### DELETE /forms/:id — Delete Form

Permanently deletes the form and all responses.

### POST /forms/:id/publish — Publish Form

Makes the form publicly accessible and generates a share URL.

### POST /forms/:id/unpublish — Unpublish Form

Removes public access. Existing share URL stops working.

### POST /forms/:id/fields — Add Field

Add a single field to an existing form.

### PATCH /forms/:id/fields/:fieldId — Update Field

Update a field's label, type, options, validation, or conditional logic.

### DELETE /forms/:id/fields/:fieldId — Delete Field

Remove a field from the form.


## 6. Responses API

### GET /forms/:id/responses — List Responses

Query parameters:
- page (number, default: 1)
- limit (number, 1-100, default: 20)
- since (ISO 8601 timestamp)

Returns paginated list of submitted responses with answer data.

### GET /forms/:id/responses/:responseId — Get Response

Returns a single response with all answers.

### GET /forms/:id/responses/count — Count Responses

Returns total response count for a form.


## 7. Smart Forms API (AI Interviews)

Smart Forms are AI-powered conversational interviews. The AI dynamically generates questions based on a purpose description — no static schema required.

### GET /smart-forms — List Smart Forms

### GET /smart-forms/:id — Get Smart Form

### POST /smart-forms — Create Smart Form

Request body:
{
  "purpose": "Evaluate customer satisfaction during hotel checkout",
  "title": "Hotel Checkout Survey",
  "description": "Share your experience to help us improve.",
  "targetAudience": "Business travelers",
  "languages": ["en", "tr"],
  "maxQuestions": 8,
  "isPrivate": false
}

Fields:
- purpose (required, 10-3000 chars): The AI uses this to generate all interview questions
- title (optional, max 200 chars)
- description (optional, max 500 chars): Shown on welcome screen
- targetAudience (optional, max 200 chars): Helps AI tailor tone
- languages (optional, string[]): ISO 639-1 codes. Empty = auto-detect. Single = locked language.
- maxQuestions (optional, 5-15, default: 10)
- isPrivate (optional, default: false): Require email OTP verification

### PATCH /smart-forms/:id — Update Smart Form

### DELETE /smart-forms/:id — Delete Smart Form

### POST /smart-forms/:id/publish — Publish Smart Form

### POST /smart-forms/:id/unpublish — Unpublish Smart Form

### GET /smart-forms/:id/sessions — List Sessions

Returns list of completed interview sessions.

### GET /smart-forms/:id/sessions/:sessionId — Get Session

Returns full Q&A transcript for a session.

### POST /smart-forms/:id/chat — Smart Form Analytics Chat

Natural language Q&A about smart form session data.

### POST /smart-forms/:id/analytics — Aggregate Analytics

Returns summary statistics across all sessions.

### GET /smart-forms/:id/export — Export Sessions

Export sessions as CSV or JSON.


## 8. Analytics API

### POST /forms/:id/smart-analytics — Trigger Smart Analytics

Dispatches an AI analytics report (async). Returns a job ID. Poll or use callback URL for results.

Requires: Pro plan or higher. Consumes AI credits.

### POST /forms/:id/analytics-chat — Analytics Chat

Natural language Q&A about form response data.

Request body:
{
  "message": "What is the average satisfaction score?",
  "sessionId": "optional-uuid-for-follow-up"
}

Supports two modes:
- JSON mode (Accept: application/json): Returns complete answer
- SSE streaming (Accept: text/event-stream): Real-time token streaming

SSE events: session, chunk, done, error

Response (JSON mode):
{
  "data": {
    "sessionId": "uuid",
    "message": "The average satisfaction score is 4.2 out of 5...",
    "suggestedActions": [
      {
        "label": { "en": "Show breakdown", "tr": "Dagilimi goster" },
        "prompt": "Show satisfaction breakdown by department"
      }
    ],
    "creditsUsed": 2
  }
}

Sessions expire after 30 minutes of inactivity. Max 10 messages per session.


## 9. Webhooks

### Overview

Formfex pushes real-time HTTP POST notifications when events occur. Webhooks include HMAC-SHA256 signatures for verification.

### Events

- FORM_RESPONSE_CREATED: New form response submitted
- FORM_PUBLISHED: Form published
- FORM_UNPUBLISHED: Form unpublished
- FORM_CREATED: Form created
- FORM_DELETED: Form deleted

### Payload Format

{
  "type": "FORM_RESPONSE_CREATED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "...",
    "formTitle": "Customer Feedback Survey",
    "responseId": "...",
    "answers": {
      "field_1": {
        "question": "How satisfied are you?",
        "answer": "Very satisfied"
      }
    }
  }
}

### Headers

- Content-Type: application/json
- X-Formfex-Signature: sha256=<hmac-sha256-hex>
- X-Formfex-Event: event type
- X-Formfex-Delivery: unique delivery ID

### Retry Policy

- Up to 8 retries with exponential backoff
- 10-second timeout per delivery
- Auto-disabled after 5 consecutive failures

### Webhook API

- GET /webhooks — List all webhooks
- POST /webhooks — Create a webhook endpoint
- PATCH /webhooks/:id — Update webhook URL or events
- DELETE /webhooks/:id — Delete a webhook


## 10. n8n Integration

### Community Node

Package: n8n-nodes-formfex
Install: Settings > Community Nodes > Install > n8n-nodes-formfex

Two nodes:
- Formfex (action) — Form CRUD, responses, AI generation, analytics
- Formfex Trigger — Fires on FORM_RESPONSE_CREATED, FORM_PUBLISHED, FORM_UNPUBLISHED

### AI Agent Tool Mode

The Formfex node supports n8n's AI Agent Tool Mode (LangChain compatible). Connect it to an AI Agent node as a tool, and LLMs (GPT-4, Claude, Gemini) can autonomously invoke Formfex operations.

5 tools exposed:

1. create_form — Create a blank form
   Parameters: title (required), description, language (en/tr/es/it/de/nl)

2. get_responses — Retrieve form responses
   Parameters: form_id (required), limit (1-100), since (ISO 8601)

3. generate_form_with_ai — Generate a complete form from natural language
   Parameters: prompt (required), language
   Handles async job lifecycle automatically (dispatch + polling)

4. analyze_form_data — Conversational Q&A about form data
   Parameters: form_id (required), question (required), session_id (for follow-ups)

5. dispatch_smart_analytics — Trigger comprehensive AI analytics report
   Parameters: form_id (required), callback_url (required, HTTPS)

### Example AI Agent Workflow

1. Customer support ticket triggers the workflow
2. AI Agent calls generate_form_with_ai to create a follow-up survey
3. Form is automatically published
4. Webhook fires when customer completes the survey
5. AI Agent calls analyze_form_data to extract key issues
6. Summary is posted to Slack via Slack node


## 11. Error Reference

| Status | Error Code | Description |
|--------|-----------|-------------|
| 400 | BAD_REQUEST | Invalid request body or parameters |
| 401 | UNAUTHORIZED | Missing, invalid, or expired API key |
| 402 | PAYMENT_REQUIRED | Feature not on current plan or insufficient credits |
| 403 | FORBIDDEN | Valid key but insufficient scope or plan |
| 404 | NOT_FOUND | Resource not found |
| 429 | TOO_MANY_REQUESTS | Rate limit or quota exceeded |
| 500 | INTERNAL_SERVER_ERROR | Unexpected server error |
| 503 | SERVICE_UNAVAILABLE | Capacity limit reached |


## 12. Common Integration Patterns

### Pattern 1: Programmatic Form Creation

POST /forms with full schema -> POST /forms/:id/publish -> Share the generated URL

### Pattern 2: Response Collection Pipeline

Create webhook for FORM_RESPONSE_CREATED -> Receive response data -> Process in your backend

### Pattern 3: AI-Powered Analysis

POST /forms/:id/analytics-chat with question -> Get AI-generated insights -> Follow up with sessionId

### Pattern 4: Smart Form Interview Automation

POST /smart-forms with purpose -> POST /smart-forms/:id/publish -> Collect sessions -> GET /smart-forms/:id/sessions for transcripts -> POST /smart-forms/:id/chat for AI analysis

### Pattern 5: n8n Workflow Automation

Formfex Trigger (new response) -> Process data -> Slack notification
AI Agent + Formfex tool -> Autonomous form lifecycle management


## Documentation Pages

### Getting Started
- Welcome: https://docs.formfex.com/en/getting-started/welcome
- Authentication: https://docs.formfex.com/en/getting-started/authentication
- Rate Limits: https://docs.formfex.com/en/getting-started/rate-limits
- Error Reference: https://docs.formfex.com/en/getting-started/error-reference

### Public API — Forms
- Overview: https://docs.formfex.com/en/public-api/overview
- List Forms: https://docs.formfex.com/en/public-api/forms/list-forms
- Get Form: https://docs.formfex.com/en/public-api/forms/get-form
- Create Form: https://docs.formfex.com/en/public-api/forms/create-form
- Update Form: https://docs.formfex.com/en/public-api/forms/update-form
- Delete Form: https://docs.formfex.com/en/public-api/forms/delete-form
- Publish Form: https://docs.formfex.com/en/public-api/forms/publish-form
- Unpublish Form: https://docs.formfex.com/en/public-api/forms/unpublish-form
- Add Field: https://docs.formfex.com/en/public-api/forms/add-field
- Update Field: https://docs.formfex.com/en/public-api/forms/update-field
- Delete Field: https://docs.formfex.com/en/public-api/forms/delete-field

### Public API — Responses
- Submit Response: https://docs.formfex.com/en/public-api/responses/submit-response
- List Responses: https://docs.formfex.com/en/public-api/responses/list-responses
- Get Response: https://docs.formfex.com/en/public-api/responses/get-response
- Count Responses: https://docs.formfex.com/en/public-api/responses/count-responses

### Public API — Smart Forms
- Create Smart Form: https://docs.formfex.com/en/public-api/smart-forms/create-smart-form
- Get Smart Form: https://docs.formfex.com/en/public-api/smart-forms/get-smart-form
- List Smart Forms: https://docs.formfex.com/en/public-api/smart-forms/list-smart-forms
- Update Smart Form: https://docs.formfex.com/en/public-api/smart-forms/update-smart-form
- Delete Smart Form: https://docs.formfex.com/en/public-api/smart-forms/delete-smart-form
- Publish Smart Form: https://docs.formfex.com/en/public-api/smart-forms/publish-smart-form
- Unpublish Smart Form: https://docs.formfex.com/en/public-api/smart-forms/unpublish-smart-form
- List Sessions: https://docs.formfex.com/en/public-api/smart-forms/list-sessions
- Get Session: https://docs.formfex.com/en/public-api/smart-forms/get-session
- Analytics Chat: https://docs.formfex.com/en/public-api/smart-forms/chat
- Aggregate Analytics: https://docs.formfex.com/en/public-api/smart-forms/aggregate-analytics
- Export Sessions: https://docs.formfex.com/en/public-api/smart-forms/export

### Public API — Analytics
- Smart Analytics: https://docs.formfex.com/en/public-api/analytics/smart-analytics
- Analytics Chat: https://docs.formfex.com/en/public-api/analytics/analytics-chat

### Public API — Account
- Get Account Info: https://docs.formfex.com/en/public-api/account/get-account-info

### n8n Integration
- Installation: https://docs.formfex.com/en/n8n/installation
- Credentials: https://docs.formfex.com/en/n8n/credentials
- Operations: https://docs.formfex.com/en/n8n/operations
- AI Agent Tool: https://docs.formfex.com/en/n8n/ai-agent-tool
- Trigger: https://docs.formfex.com/en/n8n/trigger
- Workflow Examples: https://docs.formfex.com/en/n8n/workflow-examples

### Webhooks
- Overview: https://docs.formfex.com/en/webhooks/overview
- Create Webhook: https://docs.formfex.com/en/webhooks/create-webhook
- List Webhooks: https://docs.formfex.com/en/webhooks/list-webhooks
- Update Webhook: https://docs.formfex.com/en/webhooks/update-webhook
- Delete Webhook: https://docs.formfex.com/en/webhooks/delete-webhook
- Events: https://docs.formfex.com/en/webhooks/events
- Security: https://docs.formfex.com/en/webhooks/security
- Example Integrations: https://docs.formfex.com/en/webhooks/example-integrations

## Links

- Formfex Homepage: https://formfex.com
- Developer Docs: https://docs.formfex.com
- Formfex Product Info (llms.txt): https://formfex.com/llms.txt
- Formfex Full Product Reference: https://formfex.com/llms-full.txt
- Summary Reference: https://docs.formfex.com/llms.txt