---
title: "List submissions"
method: GET
path: "/v1/forms/{form_id}/submissions"
tags: ["submissions"]
---

# List submissions

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

## Request

- Base URL: `https://api.formcarry.com`
- URL: `https://api.formcarry.com/v1/forms/{form_id}/submissions`
- Auth: HTTP bearer

Returns a form's submissions, newest first (unless you ask for the oldest).

Narrow the list with the filters below; several filters combine with AND.

To get the next page, pass a response's next_cursor as cursor and keep going until next_cursor is null. A page can occasionally hold fewer than limit results even when more exist, so rely on next_cursor, not on the page size.

## Path parameters

- `form_id` string, required

## Query parameters

- `status` 'inbox' | 'spam' | 'all'
- `read` 'true' | 'false'
- `has_attachments` 'true' | 'false'
- `created_after` string
- `created_before` string
- `country` string
- `q` string
- `order` 'newest' | 'oldest'
- `limit` number
- `cursor` string
- `fields` string

## Response `200`

- SubmissionList
  - `data` SubmissionResource[], required
    - `id` string, required
    - `form_id` string, required
    - `created_at` string, required
    - `spam` boolean, required
    - `read` boolean, required
    - `ip` string, nullable, required: The address the submission came from, or null when unknown.
    - `country` string, nullable, required: Two letter uppercase code from the address, or null when unknown.
    - `user_agent` string, nullable, required: The visitor's browser, as it announced itself, or null.
    - `referer` string, nullable, required: The page the form was on, as the browser reported it, or null.
    - `fields` SubmissionField[], required
      - `key` string, required
      - `value` string, required
    - `attachments` SubmissionAttachment[], required
      - `key` string, required
      - `url` string, required
      - `mime_type` string, nullable, required
  - `has_more` boolean, required: Whether another page exists. When true, request it with next_cursor.
  - `next_cursor` string, nullable, required

## Other responses

- `400`: A query parameter is wrong.
- `401`: The request carried no usable key or token.
- `403`: The key is valid but may not do this.
- `404`: No such form for this key, or no such submission on it.
- `422`: The request took too long; narrow the date range and retry.
- `429`: Slow down and retry after the Retry-After header.

---

[API](https://skmtc.dev/formcarry/apis/formcarry-api.md) · [All operations](https://skmtc.dev/formcarry/apis/formcarry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formcarry/apis/formcarry-api/revisions/c971f37d5987?raw)