---
title: "List Submissions API Reference"
description: "Retrieve form submissions via the Forminit REST API. Covers authentication, query parameters, response formats, and code examples."
url: https://forminit.com/docs/list-submissions-api/
---

# 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:

1. Go to **Account → API Tokens** in your Forminit dashboard
2. Click **Create Token**
3. Copy and securely store your token

> **Caution**
>
> Never expose your API key in client-side code or public repositories. API keys should only be used in server-side applications.

---

## 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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)

```json
{
  "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.

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

```json
{
  "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.

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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

```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

```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
<?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

```js
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

1. **Use pagination efficiently** – Request only the data you need. Use smaller page sizes for faster responses.

2. **Cache responses** – If your data doesn't change frequently, cache API responses to reduce requests.

3. **Handle errors gracefully** – Always check for error responses and implement retry logic for transient failures.

4. **Secure your API key** – Store API keys in environment variables and never expose them in client-side code.

5. **Use timezone parameter** – Specify a timezone to get dates formatted for your users' locale.

6. **Filter with query parameter** – Use the `query` parameter to search instead of fetching all submissions and filtering client-side.

---

## Related Documentation

- [Form Blocks Reference](https://forminit.com/docs/form-blocks/) – Complete reference for all block types
- [File Uploads](https://forminit.com/docs/file-upload/) – File upload handling guide
- [Webhooks](https://forminit.com/docs/webhooks/) – Real-time submission notifications