Read Submissions API

Read your form submissions programmatically using authenticated API requests. This is useful for displaying submissions in a custom admin area, syncing data with external tools, or building dashboards.

Authentication

All read endpoints require a Bearer token. Create one from the API Tokens page in your dashboard under the Account section.

Include the token in every request:

Authorization: Bearer your-token-here

Endpoints

List Submissions

GET /api/v1/forms/{form_id}/submissions

Returns a paginated list of submissions for the given form.

Query Parameters

Parameter	Default	Description
`per_page`	`15`	Number of results per page (max 100).
`page`	`1`	Page number.
`sort`	`created_at_desc`	Sort order. Use `created_at_asc` for oldest first.
`filter[is_read]`	—	Filter by read status (`true` or `false`).
`filter[marked_as_spam]`	—	Filter by spam status (`true` or `false`).
`filter[created_after]`	—	Only include submissions created after this date (`YYYY-MM-DD`).
`filter[created_before]`	—	Only include submissions created before this date (`YYYY-MM-DD`).

Example Request

curl https://headless-form.robertboes.nl/api/v1/forms/01JCK.../submissions?per_page=10&filter[is_read]=false \
  -H "Authorization: Bearer your-token-here"

Example Response

{
  "data": [
    {
      "id": "01JCK...",
      "form_id": "01JCK...",
      "data": {
        "name": "Alex",
        "email": "alex@example.com",
        "message": "Hello!"
      },
      "additional_data": null,
      "is_read": false,
      "marked_as_spam": false,
      "created_at": "2026-02-20T12:00:00+00:00",
      "updated_at": "2026-02-20T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "...?page=1",
    "last": "...?page=3",
    "prev": null,
    "next": "...?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 10,
    "total": 25
  }
}

Show Submission

GET /api/v1/forms/{form_id}/submissions/{submission_id}

Returns a single submission. The submission must belong to the specified form.

Example Request

curl https://headless-form.robertboes.nl/api/v1/forms/01JCK.../submissions/01JCK... \
  -H "Authorization: Bearer your-token-here"

Example Response

{
  "data": {
    "id": "01JCK...",
    "form_id": "01JCK...",
    "data": {
      "name": "Alex",
      "email": "alex@example.com",
      "message": "Hello!"
    },
    "additional_data": null,
    "is_read": false,
    "marked_as_spam": false,
    "created_at": "2026-02-20T12:00:00+00:00",
    "updated_at": "2026-02-20T12:00:00+00:00"
  }
}

Error Responses

Status	Reason
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	Token does not have the required ability, or you are not a member of the form's team.
`404 Not Found`	Form or submission does not exist.
`429 Too Many Requests`	Rate limit exceeded (60 requests per minute).

See Error Responses for the standard error format.

Rate Limiting

Read endpoints are rate limited to 60 requests per minute per authenticated user.

JavaScript Example

const API_TOKEN = 'your-token-here';
const FORM_ID = '01JCK...';

const response = await fetch(
  `https://headless-form.robertboes.nl/api/v1/forms/${FORM_ID}/submissions?per_page=20`,
  {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Accept': 'application/json',
    },
  }
);

const { data, meta } = await response.json();
console.log(`Showing ${data.length} of ${meta.total} submissions`);