POST/forms/:id/smart-analytics

Smart Analytics

Generate AI-powered analytics reports for form responses

Scope: ANALYTICS_READ

Overview

Triggers an asynchronous AI-powered analytics report for the form's responses. The report is delivered to your callback URL via a webhook when processing completes. Returns HTTP 202 Accepted with a jobId and reportId.

Plan Requirement

Smart Analytics requires a Pro plan or higher and consumes AI credits.

Request

POST/forms/:id/smart-analytics

Path Parameters

Headers

Header	Value
`Authorization`	`Bearer fxk_live_<your-api-key>`
`Content-Type`	`application/json`

Request Body

Example Request

curl -X POST "https://api.formfex.com/api/v1/public/forms/FORM_ID/smart-analytics" \
  -H "Authorization: Bearer $FORMFEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callbackUrl": "https://your-server.com/webhooks/analytics" }'

Response

Webhook Callback

When the AI worker completes processing, a POST request is sent to your callbackUrl with the full report.

Callback Headers

Header	Description
`Content-Type`	`application/json`
`X-FormFex-Event`	`smart_analytics.completed`
`X-FormFex-Signature-256`	HMAC-SHA256 signature of the request body for verification

Callback Body

json

{
  "event": "smart_analytics.completed",
  "reportId": "rp1a2b3c4-...",
  "formId": "d4e5f6a7-...",
  "formTitle": "Customer Feedback Survey",
  "metrics": {
    "totalResponses": 142,
    "responseGrowth": 12.5,
    "completionRate": 87.3,
    "totalQuestions": 10,
    "responseVolume": [
      { "date": "2026-03-01", "count": 15 }
    ],
    "fieldCompletionRates": [
      { "label": "Email", "skipRate": 0.02, "required": true }
    ],
    "questionBreakdowns": [
      {
        "label": "How would you rate our service?",
        "fieldType": "select",
        "totalResponses": 142,
        "options": [
          { "label": "Excellent", "count": 65, "percentage": 45.8 }
        ]
      }
    ],
    "insightAlerts": [
      { "type": "high_skip_rate", "severity": "warning", "message": "...", "fieldLabel": "Phone" }
    ]
  },
  "analysis": "AI-generated analysis text...",
  "creditsUsed": 5,
  "generatedAt": "2026-03-09T12:00:00.000Z"
}

Error Cases

Status	Condition
`400`	Callback URL is not HTTPS or resolves to an internal IP address
`402`	Feature not available on current plan, insufficient AI credits, or storage quota exceeded
`429`	AI endpoint rate limit exceeded (see Rate Limits)

Cooldown

Smart Analytics has a 24-hour cooldown per form. You cannot trigger a new report for the same form within 24 hours of the last run.

Verify Signatures

Verify the X-FormFex-Signature-256 header by computing sha256=HMAC-SHA256(body, secret) using your integration HMAC secret. This prevents spoofed callback deliveries.

PreviousCount Responses NextAnalytics Chat