List Submissions API Reference

Retrieve form submissions programmatically using the Forminit REST API.

Authentication Required: This endpoint requires an API key. Generate your API key from Account → API Tokens in the Forminit dashboard.

Overview

The Get Form Submissions API allows you to retrieve, search, and paginate through all submissions for a specific form. Use this endpoint to:

Export submissions to your own systems
Build custom dashboards and reporting
Integrate form data into your backend workflows
Sync submissions with CRMs, databases, or other services

Endpoint

GET https://api.forminit.com/v1/forms/{formId}

Method	URL	Description
`GET`	`/v1/forms/{formId}`	List all submissions for a form

Authentication

All requests must include your API key in the X-API-Key header.

X-API-Key: fi_your_secret_api_key

To generate an API key:

Go to Account → API Tokens in your Forminit dashboard
Click Create Token
Copy and securely store your token

Parameters

Path Parameters

Parameter	Type	Required	Description
`formId`	string	✓	The unique identifier of the form (e.g., `YOUR-FORM-ID`)

Header Parameters

Parameter	Type	Required	Description
`X-API-Key`	string	✓	Your secret API key for authentication
`Accept`	string	-	Response format. Use `application/json`

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number for paginated results
`size`	integer	`30`	Number of submissions per page. Min: `1`, Max: `100`
`query`	string	-	Search keyword to filter submissions
`files`	boolean	`false`	When `true`, includes file metadata for each submission
`timezone`	string	`UTC`	IANA timezone for date formatting (e.g., `America/New_York`, `Europe/London`)

Request Examples

Basic Request

Retrieve the first page of submissions with default settings:

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Paginated Request

Retrieve page 2 with 50 submissions per page:

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID?page=2&size=50' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Search Submissions

Search for submissions containing a specific keyword:

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID?query=john@example.com' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Include File Metadata

Retrieve submissions with file attachment details:

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID?files=true' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Custom Timezone

Format dates in a specific timezone:

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID?timezone=America/New_York' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Combined Parameters

curl -X GET \
  'https://api.forminit.com/v1/forms/YOUR-FORM-ID?page=1&size=25&query=enterprise&files=true&timezone=Europe/London' \
  -H 'X-API-Key: fi_your_secret_api_key' \
  -H 'Accept: application/json'

Response

Success Response (200)

{
  "data": {
    "id": "YOUR-FORM-ID",
    "apiVersion": "1.1",
    "submissions": [
      {
        "id": "sub_33by3euq9dgap76",
        "submissionDate": "2025-07-17T14:14:24.000000Z",
        "status": true,
        "submissionStatus": "open",
        "blocks": {
          "sender": {
            "userId": "user_12345",
            "fullName": "John Doe",
            "email": "john.doe@example.com",
            "phone": "+12025550123",
            "company": "Example Corp",
            "position": "Manager",
            "address": "456 Business Rd, Worktown",
            "country": "US"
          },
          "tracking": {
            "utmSource": "google",
            "utmMedium": "cpc",
            "utmCampaign": "winter_sale",
            "utmTerm": "discount shoes",
            "utmContent": "banner_ad",
            "referrer": "affiliate_link"
          },
          "comments": "Looking forward to the event.",
          "attendees_count": 4,
          "event_rating": 5,
          "contact_email": "support@example.com",
          "website": "https://example.com",
          "support_phone": "+1234567890",
          "selected_country": "US"
        },
        "files": [
          {
            "url": "https://example.com/file.pdf",
            "name": "file.pdf",
            "label": "resume",
            "size": 12345,
            "type": "application/pdf"
          }
        ]
      }
    ],
    "pagination": {
      "count": 30,
      "currentPage": 1,
      "total": 42,
      "firstPage": 1,
      "lastPage": 2,
      "size": 30
    }
  }
}

Response Fields

Root Object

Field	Type	Description
`data`	object	Container for all response data

Data Object

Field	Type	Description
`id`	string	The form identifier
`apiVersion`	string	Current API version
`submissions`	array	Array of submission objects
`pagination`	object	Pagination metadata

Submission Object

Field	Type	Description
`id`	string	Unique submission identifier (e.g., `sub_33by3euq9dgap76`)
`submissionDate`	string	ISO 8601 timestamp of submission
`status`	boolean	Whether the submission is active
`submissionStatus`	string	Current status: `open`, `closed`, or `spam`
`blocks`	object	All submitted field values (see below)
`files`	array	File attachments (only when `files=true`)

Blocks Object

The blocks object contains all submitted data organized by block type:

Block	Type	Description
`sender`	object	Submitter information (email, name, phone, etc.)
`tracking`	object	UTM parameters and attribution data
`{fieldName}`	varies	Single block values keyed by their field name

Sender Block Properties:

Property	Type	Description
`email`	string	Submitter’s email address
`firstName`	string	Submitter’s first name
`lastName`	string	Submitter’s last name
`fullName`	string	Submitter’s full name
`phone`	string	Phone number (E.164 format)
`userId`	string	User ID from your system
`company`	string	Company name
`position`	string	Job title
`address`	string	Street address
`city`	string	City
`country`	string	Country (ISO alpha-2 code)

Tracking Block Properties:

Property	Type	Description
`utmSource`	string	Campaign traffic source
`utmMedium`	string	Marketing medium
`utmCampaign`	string	Campaign name
`utmTerm`	string	Paid keyword
`utmContent`	string	Ad variant identifier
`referrer`	string	Referring URL
`gclid`	string	Google Ads click ID
`fbclid`	string	Facebook click ID

File Object

Returned when files=true query parameter is set:

Field	Type	Description
`url`	string	Direct URL to download the file
`name`	string	Original filename
`label`	string	Field name/label for the file input
`size`	integer	File size in bytes
`type`	string	MIME type (e.g., `application/pdf`)

Pagination Object

Field	Type	Description
`count`	integer	Number of submissions in current response
`currentPage`	integer	Current page number
`total`	integer	Total number of submissions
`firstPage`	integer	First page number (always `1`)
`lastPage`	integer	Last page number
`size`	integer	Page size used for this request

Error Responses

400 Bad Request

Returned when the request is malformed or contains invalid parameters.

{
  "success": false,
  "error": "FORM_ID_REQUIRED",
  "code": 400,
  "message": "Form ID is required. Please check the form ID and try again."
}

{
  "success": false,
  "error": "INVALID_SIZE_PARAMETER",
  "code": 400,
  "message": "Size parameter must be between 1 and 100."
}

401 Unauthorized

Returned when the API key is missing, invalid, or lacks required permissions.

{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": 401,
  "message": "Missing X-API-KEY key in the header"
}

{
  "success": false,
  "error": "INVALID_API_KEY",
  "code": 401,
  "message": "Invalid API key provided."
}

404 Not Found

Returned when the form does not exist or has been deleted.

{
  "success": false,
  "error": "FORM_NOT_FOUND",
  "code": 404,
  "message": "This form has been deleted and is no longer available. Please contact support if you believe this is an error."
}

429 Too Many Requests

Returned when rate limits are exceeded.

{
  "success": false,
  "error": "TOO_MANY_REQUESTS",
  "code": 429,
  "message": "Rate limit exceeded. Maximum 5 requests per second allowed.",
  "suggest": "Wait a moment before making another request."
}

Response Codes Summary

Status Code	Description
`200`	Success – Submissions retrieved successfully
`400`	Bad Request – Invalid form ID or parameters
`401`	Unauthorized – Missing or invalid API key
`404`	Not Found – Form does not exist or was deleted
`429`	Too Many Requests – Rate limit exceeded
`500`	Internal Server Error – Unexpected server error

Code Examples

Node.js

import { Forminit } from 'forminit';

const forminit = new Forminit({
  apiKey: process.env.FORMINIT_API_KEY,
});

async function getSubmissions(formId, options = {}) {
  const { page = 1, size = 30, query, files, timezone } = options;
  
  const params = new URLSearchParams({
    page: page.toString(),
    size: size.toString(),
  });
  
  if (query) params.append('query', query);
  if (files) params.append('files', 'true');
  if (timezone) params.append('timezone', timezone);
  
  const response = await fetch(
    `https://api.forminit.com/v1/forms/${formId}?${params}`,
    {
      headers: {
        'X-API-Key': process.env.FORMINIT_API_KEY,
        'Accept': 'application/json',
      },
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  return response.json();
}

// Usage
const result = await getSubmissions('YOUR-FORM-ID', {
  page: 1,
  size: 50,
  files: true,
  timezone: 'America/New_York',
});

console.log(`Total submissions: ${result.data.pagination.total}`);
console.log(`Current page: ${result.data.pagination.currentPage}`);

for (const submission of result.data.submissions) {
  console.log(`ID: ${submission.id}`);
  console.log(`Email: ${submission.blocks.sender?.email}`);
  console.log(`Date: ${submission.submissionDate}`);
}

Python

import requests
import os

def get_submissions(form_id, page=1, size=30, query=None, files=False, timezone=None):
    url = f"https://api.forminit.com/v1/forms/{form_id}"
    
    params = {
        "page": page,
        "size": size,
    }
    
    if query:
        params["query"] = query
    if files:
        params["files"] = "true"
    if timezone:
        params["timezone"] = timezone
    
    headers = {
        "X-API-Key": os.environ.get("FORMINIT_API_KEY"),
        "Accept": "application/json",
    }
    
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    
    return response.json()

# Usage
result = get_submissions(
    form_id="YOUR-FORM-ID",
    page=1,
    size=50,
    files=True,
    timezone="Europe/London"
)

print(f"Total submissions: {result['data']['pagination']['total']}")

for submission in result["data"]["submissions"]:
    print(f"ID: {submission['id']}")
    sender = submission["blocks"].get("sender", {})
    print(f"Email: {sender.get('email')}")

PHP

<?php

function getSubmissions($formId, $options = []) {
    $params = array_merge([
        'page' => 1,
        'size' => 30,
    ], $options);
    
    $queryString = http_build_query(array_filter($params));
    $url = "https://api.forminit.com/v1/forms/{$formId}?{$queryString}";
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . getenv('FORMINIT_API_KEY'),
            'Accept: application/json',
        ],
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("API request failed with status {$httpCode}");
    }
    
    return json_decode($response, true);
}

// Usage
$result = getSubmissions('YOUR-FORM-ID', [
    'page' => 1,
    'size' => 50,
    'files' => 'true',
]);

echo "Total submissions: " . $result['data']['pagination']['total'] . "\n";

foreach ($result['data']['submissions'] as $submission) {
    echo "ID: " . $submission['id'] . "\n";
    echo "Email: " . ($submission['blocks']['sender']['email'] ?? 'N/A') . "\n";
}

Pagination

The API uses page-based pagination. Use the pagination object in the response to navigate through results.

Fetching All Submissions

async function getAllSubmissions(formId) {
  const allSubmissions = [];
  let currentPage = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api.forminit.com/v1/forms/${formId}?page=${currentPage}&size=100`,
      {
        headers: {
          'X-API-Key': process.env.FORMINIT_API_KEY,
          'Accept': 'application/json',
        },
      }
    );
    
    const result = await response.json();
    allSubmissions.push(...result.data.submissions);
    
    const { currentPage: page, lastPage } = result.data.pagination;
    hasMore = page < lastPage;
    currentPage++;
  }
  
  return allSubmissions;
}

Best Practices

Use pagination efficiently – Request only the data you need. Use smaller page sizes for faster responses.
Cache responses – If your data doesn’t change frequently, cache API responses to reduce requests.
Handle errors gracefully – Always check for error responses and implement retry logic for transient failures.
Secure your API key – Store API keys in environment variables and never expose them in client-side code.
Use timezone parameter – Specify a timezone to get dates formatted for your users’ locale.
Filter with query parameter – Use the query parameter to search instead of fetching all submissions and filtering client-side.

Form Blocks Reference – Complete reference for all block types
File Uploads – File upload handling guide
Webhooks – Real-time submission notifications