Overview
Introduction to the Formfex Public API
Introduction
The Formfex Public API lets you programmatically manage forms, retrieve responses, trigger AI-powered analytics, and configure webhooks. All endpoints are RESTful and return JSON responses.
Base URL:
https://api.formfex.com/api/v1/public
Authentication
All requests must include an API key in the Authorization header as a Bearer token:
curl -H "Authorization: Bearer fxk_live_<keyId>.<secret>" \
https://api.formfex.com/api/v1/public/forms
API keys are scoped — each key only has access to the endpoints allowed by its assigned scopes. See Authentication for details on creating and managing keys.
Response Format
All responses are wrapped in a consistent envelope:
{
"message": "Human-readable status message",
"data": { },
"error": null
}
| Field | Type | Description |
|---|---|---|
message | string | Translated status message |
data | T | null | Response payload (varies by endpoint) |
error | string | null | Error details when applicable |
Available Endpoints
Forms
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /forms | List all forms | FORMS_READ |
GET | /forms/:id | Get a single form | FORMS_READ |
POST | /forms | Create a new form | FORMS_WRITE |
PATCH | /forms/:id | Update a form | FORMS_WRITE |
DELETE | /forms/:id | Delete a form | FORMS_WRITE |
POST | /forms/:id/publish | Publish a form | FORMS_WRITE |
POST | /forms/:id/unpublish | Unpublish a form | FORMS_WRITE |
POST | /forms/:id/fields | Add a field | FORMS_WRITE |
PATCH | /forms/:id/fields/:fieldId | Update a field | FORMS_WRITE |
DELETE | /forms/:id/fields/:fieldId | Delete a field | FORMS_WRITE |
Responses
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /forms/:id/responses | List form responses | RESPONSES_READ |
GET | /forms/:id/responses/:responseId | Get a single response | RESPONSES_READ |
GET | /forms/:id/responses/count | Count responses | RESPONSES_READ |
Analytics
| Method | Endpoint | Description | Scope |
|---|---|---|---|
POST | /forms/:id/smart-analytics | Trigger smart analytics | ANALYTICS_READ |
POST | /forms/:id/analytics-chat | Analytics chat | ANALYTICS_READ |
Account
| Method | Endpoint | Description | Scope |
|---|---|---|---|
GET | /me | Get account info | FORMS_READ |
Rate Limits
The API enforces per-minute, per-hour, and monthly rate limits based on your plan. Every response includes rate limit headers so you can track usage. See Rate Limits for details.
Error Handling
Common error status codes across all endpoints:
| Status | Description |
|---|---|
400 Bad Request | Invalid request body or query parameters |
401 Unauthorized | Missing, invalid, revoked, or expired API key |
403 Forbidden | Insufficient scope or plan restriction |
404 Not Found | Resource not found |
429 Too Many Requests | Rate limit or monthly quota exceeded |
Rate Limit Headers
Check the Retry-After header on 429 responses for the exact number of seconds to wait before retrying.