FormlyIQ REST API

The FormlyIQ API lets you manage forms and submissions programmatically. All API requests are made over HTTPS to https://formlyiq.itsmiarosemathews.workers.dev.

Use the API to build custom integrations, pull submission data into your own systems, create forms dynamically, or automate workspace management.

Authentication

Authenticate by passing your API key in the X-FormlyIQ-Key header. Create API keys from Settings → API Keys in your dashboard.

⚠️

Keep your API key secret. It grants full access to your workspace. Never expose it in client-side JavaScript or commit it to version control.

Errors

FormlyIQ uses standard HTTP status codes. All error responses include an error string and sometimes an errors object for validation failures.

Code	Meaning
200	Success
201	Created
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — valid key but insufficient permissions
404	Not found
409	Conflict — e.g. slug already in use
422	Validation failed — check the `errors` object
429	Rate limited

Rate limits

Public form submission endpoints (POST /f/:id) are rate limited to 10 submissions per IP per hour by default. API endpoints are rate limited to 1,000 requests per minute per API key.

Base URL

https://formlyiq.itsmiarosemathews.workers.dev

Authentication

curl https://formlyiq.itsmiarosemathews.workers.dev/api/forms \
  -H "X-FormlyIQ-Key: fit_your_key_here"

401Unauthorized

{
  "error": "Authentication required",
  "code": "UNAUTHENTICATED"
}

Forms API

Create, read, update, and delete forms. Forms belong to a workspace and are scoped to your authenticated API key.

GET/api/forms

List forms

Returns all forms in the authenticated workspace. Pass workspace_id to scope to a specific workspace.

Query parameters

Parameter	Type	Description
workspace_idoptional	string	Filter by workspace ID
searchoptional	string	Search forms by name or description

Request

curl https://formlyiq.itsmiarosemathews.workers.dev/api/forms \
  -H "X-FormlyIQ-Key: fit_your_key"

200OK

{
  "forms": [
    {
      "id": "abc123xyz",
      "name": "Contact Us",
      "custom_slug": "contact",
      "submission_count": 847,
      "is_active": true,
      "workspace_id": "ws_xyz",
      "created_at": 1744182394000
    }
  ]
}

POST/api/forms

Create form

Creates a new form with the given fields and settings.

Body parameters

Parameter	Type	Description
namerequired	string	Display name of the form
description	string	Optional description
fields	array	Array of field objects (see Field schema)
custom_slug	string	URL slug, e.g. `contact` → `/f/contact`
webhook_url	string	URL to POST submissions to
workspace_id	string	Workspace to create form in
settings	object	Form settings (see Settings schema)

Field schema

Field	Type	Description
id	string	Stable snake_case field ID, e.g. `contact_email`
labelrequired	string	Display label shown to users
type	string	Field type: text, email, tel, number, url, textarea, select, checkbox, date, file, hidden
required	boolean	Whether field is required
placeholder	string	Placeholder text
options	array	Options for select fields
validation	object	Validation rules (minLength, maxLength, pattern, etc.)

Request

curl -X POST https://formlyiq.itsmiarosemathews.workers.dev/api/forms \
  -H "X-FormlyIQ-Key: fit_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Us",
    "custom_slug": "contact",
    "fields": [
      {
        "id": "full_name",
        "label": "Full Name",
        "type": "text",
        "required": true
      },
      {
        "id": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "settings": {
      "notifyEmail": "[email protected]",
      "successMessage": "Thanks!"
    }
  }'

201Created

{
  "form": {
    "id": "abc123xyz",
    "name": "Contact Us",
    "custom_slug": "contact",
    "fields": [...],
    "is_active": true,
    "created_at": 1744182394000
  }
}

Submissions API

Submit forms and retrieve, search, and export submission data.

POST/f/:id

Submit a form

Public endpoint — no API key required. Accepts JSON, URL-encoded, or multipart form data. The :id can be the form ID or custom slug.

Supported content types

Content-Type	Use case
`application/json`	JavaScript fetch / AJAX submissions
`application/x-www-form-urlencoded`	Default HTML form POST
`multipart/form-data`	HTML forms with file uploads

Special fields

Field name	Description
`cf-turnstile-response`	Cloudflare Turnstile token (required if Turnstile enabled)
`utm_source`, `utm_medium`, `utm_campaign`	UTM tracking — captured in analytics, not stored in submission data

HTML form

<form action="https://formlyiq.itsmiarosemathews.workers.dev/f/contact"
      method="POST">
  <input name="email" type="email" required>
  <button type="submit">Send</button>
</form>

JavaScript fetch

const res = await fetch(
  'https://formlyiq.itsmiarosemathews.workers.dev/f/contact',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      full_name: 'Jane Smith',
      email: '[email protected]',
      message: 'Hello!'
    })
  }
);
const data = await res.json();
// { success: true, submissionId: "17441..." }

201Created

{
  "success": true,
  "submissionId": "17441823940004729183",
  "message": "Form submitted successfully"
}

422Validation failed

{
  "error": "Validation failed",
  "errors": {
    "email": "Please enter a valid email",
    "full_name": "Full Name is required"
  }
}

GET/api/forms/:id/submissions

List submissions

Returns paginated submissions for a form. Supports search, date filtering, and sorting.

Query parameters

Parameter	Type	Description
page	integer	Page number, default 1
limit	integer	Results per page, max 200, default 50
search	string	Full-text search across all field values
sort	string	`created_at` (default)
dir	string	`desc` (default) or `asc`
from	integer	Start timestamp in epoch ms
to	integer	End timestamp in epoch ms

Request

curl "https://formlyiq.itsmiarosemathews.workers.dev/api/forms/abc123/submissions\
?search=jane&limit=10&dir=desc" \
  -H "X-FormlyIQ-Key: fit_your_key"

200OK

{
  "submissions": [
    {
      "id": "17441823940004729183",
      "form_id": "abc123xyz",
      "data": {
        "full_name": "Jane Smith",
        "email": "[email protected]"
      },
      "files": [],
      "ip_address": "1.2.3.4",
      "created_at": 1744182394000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 847,
    "pages": 85
  }
}

GET/api/search

Search across all forms

Full-text search across all submissions in a workspace. Returns matching submissions with their form name attached.

Query parameters

Parameter	Type	Description
q	string	Search query
workspace_id	string	Scope to a specific workspace
form_id	string	Scope to a specific form
page	integer	Page number
limit	integer	Max 100

Request

curl "https://formlyiq.itsmiarosemathews.workers.dev/api/search?q=jane" \
  -H "X-FormlyIQ-Key: fit_your_key"

200OK

{
  "results": [
    {
      "id": "17441823940004729183",
      "form_name": "Contact Us",
      "data": { "email": "[email protected]" },
      "created_at": 1744182394000
    }
  ],
  "pagination": { "total": 12, "page": 1 }
}

GET/api/forms/:id/export

Export submissions

Download all submissions for a form as CSV, JSON, or JSONL. Respects optional search filter.

Query parameters

Parameter	Type	Description
format	string	`csv` (default), `json`, or `jsonl`
search	string	Optional filter — export only matching submissions

Request

curl "https://formlyiq.itsmiarosemathews.workers.dev/api/forms/abc123/export\
?format=jsonl" \
  -H "X-FormlyIQ-Key: fit_your_key" \
  -o submissions.jsonl

200application/x-ndjson

{"_id":"17441...","_created_at":"2026-04-08T...","email":"[email protected]"}
{"_id":"17441...","_created_at":"2026-04-08T...","email":"[email protected]"}
...

Analytics API

Retrieve analytics data and submission logs for forms and workspaces.

GET/api/forms/:id/analytics

Form analytics

Returns analytics data for a specific form including submission volume by day, device breakdown, UTM campaign data, country distribution, and browser stats.

Query parameters

Parameter	Type	Description
days	integer	Lookback window in days, default 30

Request

curl "https://formlyiq.itsmiarosemathews.workers.dev/api/forms/abc123/analytics\
?days=30" \
  -H "X-FormlyIQ-Key: fit_your_key"

200OK

{
  "total": 847,
  "days": 30,
  "byDay": [
    { "day": "2026-04-08", "count": 43 }
  ],
  "byDevice": [
    { "device_type": "desktop", "count": 491 },
    { "device_type": "mobile", "count": 305 }
  ],
  "byCountry": [
    { "country": "US", "count": 612 }
  ],
  "byUTMSource": [
    { "utm_source": "google", "count": 384 }
  ]
}

Workspaces API

Manage workspaces, team members, and invitations.

POST/api/workspaces/:id/invites

Invite a member

Sends an email invitation to join the workspace. Requires admin or owner role. Invites expire after 7 days.

Body parameters

Parameter	Type	Description
emailrequired	string	Email address to invite
role	string	`admin`, `member` (default), or `viewer`

Request

curl -X POST \
  https://formlyiq.itsmiarosemathews.workers.dev/api/workspaces/ws_xyz/invites \
  -H "X-FormlyIQ-Key: fit_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member"
  }'

201Created

{
  "success": true,
  "inviteId": "inv_abc123",
  "message": "Invite sent to [email protected]"
}

API Keys API

Manage programmatic access tokens for your workspace.

POST/api/keys

Create API key

Creates a new API key. The full key value is only returned once — store it immediately. Only a SHA-256 hash is saved in the database.

Body parameters

Parameter	Type	Description
namerequired	string	Descriptive name for the key
workspace_id	string	Scope key to a specific workspace

Request

curl -X POST https://formlyiq.itsmiarosemathews.workers.dev/api/keys \
  -H "X-FormlyIQ-Key: fit_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production integration" }'

201Created

{
  "id": "key_abc123",
  "key": "fit_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Production integration",
  "note": "Save this key — it will not be shown again"
}

Need help with the API? Email