Submissions

Overview

The Submissions API handles form submissions, response retrieval, and export functionality. Submissions can be made publicly (without authentication) or via authenticated API requests.

Endpoints

Submit Form

Submit a response to a form.

Endpoint: POST /forms/{id}/submit

Authentication: Optional (API key recommended for server-side, publishable key for client-side)

Path Parameters:

id (required): Form ID

Request Body:

{
  "answers": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello world"
  },
  "sessionId": "session_123",
  "recaptchaToken": "token_from_recaptcha"
}

Response: 201 Created

{
  "id": "rsp_456",
  "submittedAt": "2024-01-01T00:00:00Z",
  "answers": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello world"
  },
  "spamChecked": true
}

Error Responses:

400: Invalid request (missing required fields, validation errors)
404: Form not found

429: Rate limit exceeded or quota exceeded

{
  "error": "Quota exceeded. You have used 1000 of 1000 submissions this month.",
  "quotaExceeded": true,
  "remaining": 0,
  "resetAt": "2024-02-01T00:00:00Z"
}

Rate Limiting:

Public submissions: Rate limited by IP address
Authenticated submissions: Rate limited by user
Retry-After header indicates when to retry

Spam Protection:

Honeypot fields (if configured)
reCAPTCHA validation (if configured)
Custom spam rules (if configured)

List Responses

List form responses with pagination.

Endpoint: GET /responses?form_id={formId}&environment={environment}

Authentication: Required (Session token)

Query Parameters:

form_id (required): Form ID
environment (required): Workspace environment
limit (optional): Items per page (default: 50, max: 100)
cursor (optional): Pagination cursor
from (optional): Start date (ISO 8601)
to (optional): End date (ISO 8601)

Response: 200 OK

{
  "items": [
    {
      "submission": {
        "id": "rsp_456",
        "formId": "form_123",
        "submittedAt": "2024-01-01T00:00:00Z",
        "answers": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "status": "completed"
      },
      "meta": {
        "read": false,
        "starred": false,
        "notes": []
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjEyMyJ9",
    "hasMore": true
  }
}

Error Responses:

400: Missing required parameters
401: Unauthorized
403: Forbidden (not form owner)
404: Form not found

Export Responses

Export form responses as CSV.

Endpoint: GET /responses?form_id={formId}&environment={environment}&format=csv

Authentication: Required (Session token)

Query Parameters:

form_id (required): Form ID
environment (required): Workspace environment
format (required): Must be csv

Response: 200 OK

Content-Type: text/csv

name,email,message,submittedAt
John Doe,john@example.com,Hello,2024-01-01T00:00:00Z
Jane Smith,jane@example.com,Hi,2024-01-02T00:00:00Z

Error Responses:

400: Missing required parameters
401: Unauthorized
404: Form not found

Get Submission

Retrieve a specific submission by ID.

Endpoint: GET /responses/{submissionId}?form_id={formId}&environment={environment}

Authentication: Required (Session token)

Path Parameters:

submissionId (required): Submission ID

Query Parameters:

form_id (required): Form ID
environment (required): Workspace environment

Response: 200 OK

{
  "submission": {
    "id": "rsp_456",
    "formId": "form_123",
    "submittedAt": "2024-01-01T00:00:00Z",
    "answers": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "status": "completed"
  },
  "meta": {
    "read": false,
    "starred": false,
    "notes": []
  }
}

Read Submission

Mark a submission as read.

Endpoint: POST /responses/{submissionId}/read

Authentication: Required (Session token)

Response: 200 OK

{
  "success": true
}

Star Submission

Star or unstar a submission.

Endpoint: POST /responses/{submissionId}/star

Authentication: Required (Session token)

Request Body:

{
  "starred": true
}

Response: 200 OK

{
  "success": true,
  "starred": true
}

Add Note

Add a note to a submission.

Endpoint: POST /responses/{submissionId}/notes

Authentication: Required (Session token)

Request Body:

{
  "note": "Follow up needed"
}

Response: 200 OK

{
  "id": "note_789",
  "note": "Follow up needed",
  "createdAt": "2024-01-01T00:00:00Z"
}

Reply to Submission

Send a reply to a submission (email).

Endpoint: POST /responses/{submissionId}/reply

Authentication: Required (Session token)

Request Body:

{
  "message": "Thank you for your submission",
  "subject": "Re: Contact Form Submission"
}

Response: 200 OK

{
  "success": true,
  "messageId": "msg_123"
}

Submission Processing

Validation

Submissions are validated against the form schema:

Required Fields: All required fields must be present
Field Types: Values must match field types (text, email, number, etc.)
Validation Rules: Min/max length, patterns, ranges are enforced
Conditional Logic: Only visible fields are accepted

Spam Protection

If spam protection is enabled:

Honeypot: Hidden fields that should remain empty
reCAPTCHA: Token validation (if configured)
Custom Rules: Field-based spam detection
Actions: reject, flag, or quarantine

Rate Limiting

IP-based: Public submissions rate limited by IP
User-based: Authenticated submissions rate limited by user
Quota: Monthly submission quotas per user/environment

PII Handling

PII fields are handled according to form configuration:

Plain: Stored as-is
Masked: Partially masked in responses
Hashed: SHA-256 hashed
Encrypted: KMS-encrypted
Dropped: Not stored

Response Metadata

Responses include metadata for management:

{
  "meta": {
    "read": false,           // Read status
    "starred": false,         // Starred status
    "notes": [],             // Admin notes
    "tags": []               // Tags
  }
}

Examples

Submit a Form (Public)

curl -X POST https://api.formr.xyz/forms/form_123/submit \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "sessionId": "session_123"
  }'

Submit a Form (Authenticated)

curl -X POST https://api.formr.xyz/forms/form_123/submit \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

List Responses

curl -X GET "https://api.formr.xyz/responses?form_id=form_123&environment=development&limit=50" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Export Responses as CSV

curl -X GET "https://api.formr.xyz/responses?form_id=form_123&environment=development&format=csv" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -o responses.csv

Next Steps

API Reference - API overview
Forms API - Form management
Analytics API - Analytics and reporting

PreviousForms NextTemplates

Last updated 1 month ago

Good night

Overview

Endpoints

Submit Form

List Responses

Export Responses

Get Submission

Read Submission

Star Submission

Add Note

Reply to Submission

Submission Processing

Validation

Spam Protection

Rate Limiting

PII Handling

Response Metadata

Examples

Submit a Form (Public)

Submit a Form (Authenticated)

List Responses

Export Responses as CSV

Next Steps