REST API

Access your Formoar data programmatically. List forms, query submissions, export data, and delete submissions — all authenticated with API keys.

API access requires a Starter plan or higher. API keys can be created in your workspace settings.

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme.

Authorization header

curl https://formoar.com/api/v1/forms \
  -H "Authorization: Bearer fmr_your_api_key"

API keys are scoped to a workspace. Any request made with a key will only access forms and submissions belonging to that workspace.

Name
Authorization
Type
header
Description
Bearer <api_key> — your API key, starting with fmr_.

Authentication errors

Name
401 Unauthorized
Description
Missing or invalid Authorization header, or the API key is invalid or expired.
Name
403 Forbidden
Description
API access is not available on your current plan. Upgrade to Starter or higher.

Rate limits

API requests are rate-limited to 100 requests per minute per API key. If you exceed this limit, the API returns a 429 status code.

429 response

{
  "error": "Rate limit exceeded"
}

GET/api/v1/forms

List forms

Returns all forms in the workspace associated with the API key. Forms are sorted by creation date (newest first).

Response fields

Name
data
Type
array
Description
Array of form objects.
Name
total
Type
integer
Description
Total number of forms.

Each form object contains:

Name
id
Type
string
Description
The form's unique ID (UUID).
Name
name
Type
string
Description
The form name.
Name
is_active
Type
boolean
Description
Whether the form is currently accepting submissions.
Name
submission_count
Type
integer
Description
Total number of submissions received.
Name
created_at
Type
string
Description
ISO 8601 timestamp of when the form was created.
Name
updated_at
Type
string
Description
ISO 8601 timestamp of the last update.

Request

curl https://formoar.com/api/v1/forms \
  -H "Authorization: Bearer fmr_your_api_key"

Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "Contact Form",
      "is_active": true,
      "submission_count": 142,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:22:00Z"
    }
  ],
  "total": 1
}

GET/api/v1/forms/:formId/submissions

List submissions

Returns paginated submissions for a specific form. The form must belong to the workspace associated with the API key.

Query parameters

Name
limit
Type
integer
Description
Number of submissions to return. Min 1, max 100, default 25.
Name
offset
Type
integer
Description
Number of submissions to skip. Default 0.
Name
search
Type
string
Description
Case-insensitive search across submission data. Max 200 characters.
Name
spam
Type
string
Description
Set to true to return spam submissions. Default false.
Name
dateFrom
Type
string
Description
Filter submissions on or after this date. Format: YYYY-MM-DD.
Name
dateTo
Type
string
Description
Filter submissions on or before this date. Format: YYYY-MM-DD.

Response fields

Name
data
Type
array
Description
Array of submission objects.
Name
total
Type
integer
Description
Total number of matching submissions (for pagination).
Name
limit
Type
integer
Description
The limit used for this request.
Name
offset
Type
integer
Description
The offset used for this request.

Each submission object contains:

Name
id
Type
string
Description
The submission's unique ID (UUID).
Name
data
Type
object
Description
Key-value pairs of the submitted form fields.
Name
is_spam
Type
boolean
Description
Whether the submission was flagged as spam.
Name
spam_reason
Type
string | null
Description
The reason the submission was flagged, if applicable.
Name
created_at
Type
string
Description
ISO 8601 timestamp of when the submission was received.
Name
ip_address
Type
string | null
Description
The IP address of the submitter.

Request

curl "https://formoar.com/api/v1/forms/FORM_ID/submissions?limit=10&offset=0" \
  -H "Authorization: Bearer fmr_your_api_key"

With date filter

curl "https://formoar.com/api/v1/forms/FORM_ID/submissions?dateFrom=2026-01-01&dateTo=2026-01-31" \
  -H "Authorization: Bearer fmr_your_api_key"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "data": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "message": "Hello!"
      },
      "is_spam": false,
      "spam_reason": null,
      "created_at": "2026-02-15T09:45:00Z",
      "ip_address": "203.0.113.42"
    }
  ],
  "total": 142,
  "limit": 10,
  "offset": 0
}

GET/api/v1/forms/:formId/export

Export submissions

Export all submissions for a form as CSV or JSON. Useful for bulk data downloads and backups. Exports up to 50,000 rows.

Export requires a Starter plan or higher. Free plans do not have access to the export feature.

Query parameters

Name
format
Type
string
Description
Export format: csv or json. Default csv.
Name
spam
Type
string
Description
Set to true to export spam submissions. Default false.
Name
dateFrom
Type
string
Description
Filter submissions on or after this date. Format: YYYY-MM-DD.
Name
dateTo
Type
string
Description
Filter submissions on or before this date. Format: YYYY-MM-DD.

Response

The response is a file download. The Content-Disposition header includes a filename based on the form name and current date.

CSV format includes all submitted form fields as columns, plus metadata columns: _submitted_at, _ip_address, _is_spam.

JSON format returns an array of objects, each containing data (the submitted fields) plus _submitted_at, _ip_address, and _is_spam metadata.

Export as CSV

curl "https://formoar.com/api/v1/forms/FORM_ID/export?format=csv" \
  -H "Authorization: Bearer fmr_your_api_key" \
  -o submissions.csv

Export as JSON

curl "https://formoar.com/api/v1/forms/FORM_ID/export?format=json" \
  -H "Authorization: Bearer fmr_your_api_key" \
  -o submissions.json

JSON export response

[
  {
    "data": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "message": "Hello!"
    },
    "_submitted_at": "2026-02-15T09:45:00Z",
    "_ip_address": "203.0.113.42",
    "_is_spam": false
  }
]

DELETE/api/v1/submissions/:submissionId

Delete submission

Permanently delete a single submission by ID. The submission must belong to a form in the workspace associated with the API key. Any files attached to the submission are also deleted from storage.

Path parameters

Name
submissionId
Type
string
Description
The submission's unique ID (UUID).

Response

Name
ok
Type
boolean
Description
true if the submission was deleted successfully.

Request

curl -X DELETE https://formoar.com/api/v1/submissions/SUBMISSION_ID \
  -H "Authorization: Bearer fmr_your_api_key"

Response

{
  "ok": true
}

Error responses

All API errors return a JSON object with an error field.

Error response format

{
  "error": "Human-readable error message"
}

Some responses also include a requestId field for debugging purposes.

Name
400 Bad Request
Description
Invalid form ID, submission ID, search query too long, or invalid export format.
Name
401 Unauthorized
Description
Missing or invalid API key.
Name
403 Forbidden
Description
API access not available on your plan, or export not available on your plan.
Name
404 Not Found
Description
Form or submission not found, or does not belong to your workspace.
Name
429 Too Many Requests
Description
API key rate limit exceeded (100 requests per minute).
Name
500 Internal Server Error
Description
An unexpected server error occurred.
Name
503 Service Unavailable
Description
The service is temporarily unavailable. Retry after a short delay.