Transactional

Submissions

Managing and processing form submissions

Form Submissions

Learn how to view, manage, and process form submissions.

Viewing Submissions

Dashboard

Navigate to Forms > Select a form > Submissions tab to see all responses.

The submissions table shows:

  • Submission date/time
  • Key field values
  • Submission status
  • Actions

API

List all submissions for a form:

const response = await fetch('/api/forms/{formId}/submissions', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data, meta } = await response.json();
// data: FormSubmission[]
// meta: { page, limit, total, totalPages }

Pagination

// Get page 2 with 50 items per page
GET /api/forms/{formId}/submissions?page=2&limit=50

Filtering

// Filter by date range
GET /api/forms/{formId}/submissions?startDate=2024-01-01&endDate=2024-01-31
 
// Filter by status
GET /api/forms/{formId}/submissions?status=complete

Submission Object

interface FormSubmission {
  id: number;
  uuid: string;
  formId: number;
  sessionId: string;
 
  // Response data
  data: Record<string, any>;
 
  // Metadata
  metadata: {
    userAgent: string;
    ipAddress: string;
    referrer: string;
    duration: number; // seconds
  };
 
  // Status
  status: 'partial' | 'complete';
 
  // Timestamps
  startedAt: string;
  completedAt: string | null;
  createdAt: string;
  updatedAt: string;
}

Getting a Single Submission

const response = await fetch('/api/forms/{formId}/submissions/{submissionId}', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Partial Submissions

Forms automatically save partial progress. Users can return and complete their submission later.

How It Works

  1. User starts filling the form
  2. Every field change triggers a partial save
  3. Session ID is stored in browser
  4. On return, progress is restored

Retrieving Partial Submissions

// Get incomplete submissions
GET /api/forms/{formId}/submissions?status=partial

Completion Rate

// Calculate completion rate
const allSubmissions = await getSubmissions(formId);
const complete = allSubmissions.filter(s => s.status === 'complete');
const completionRate = complete.length / allSubmissions.length;

Exporting Submissions

CSV Export

// Export via API
const response = await fetch('/api/forms/{formId}/submissions/export?format=csv', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const csvContent = await response.text();

JSON Export

// Export as JSON
const response = await fetch('/api/forms/{formId}/submissions/export?format=json', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const submissions = await response.json();

Deleting Submissions

Single Submission

await fetch('/api/forms/{formId}/submissions/{submissionId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Bulk Delete

await fetch('/api/forms/{formId}/submissions/bulk-delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    submissionIds: ['uuid-1', 'uuid-2', 'uuid-3'],
  }),
});

Submission Notifications

Email Notifications

Configure email notifications for new submissions:

// In form settings
{
  notificationEmails: ['team@example.com', 'admin@example.com']
}

Email includes:

  • All submitted field values
  • Submission timestamp
  • Link to view in dashboard

Webhook Notifications

Trigger webhooks for real-time integrations:

// In form settings
{
  webhookUrl: 'https://your-server.com/webhook/forms'
}

Webhook payload:

{
  "event": "form.submission.created",
  "form": {
    "id": "form-uuid",
    "title": "Contact Form"
  },
  "submission": {
    "id": "submission-uuid",
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello!"
    },
    "metadata": {
      "submittedAt": "2024-01-15T10:30:00Z"
    }
  }
}

File Attachments

For forms with file upload fields, access attachments:

const submission = await getSubmission(formId, submissionId);
 
// File data includes URL
const fileUrl = submission.data.resume.url;
const fileName = submission.data.resume.name;
const fileSize = submission.data.resume.size;

Download Files

// Download a specific file
const response = await fetch('/api/forms/{formId}/submissions/{submissionId}/files/{fieldId}', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const blob = await response.blob();

Spam Protection

Submissions are automatically filtered for spam:

  • Rate limiting per IP
  • Honeypot fields
  • reCAPTCHA integration (optional)

Marking as Spam

await fetch('/api/forms/{formId}/submissions/{submissionId}/spam', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
  },
});

Next Steps