---
title: "Search submissions across forms"
method: GET
path: "/v1/submissions"
tags: ["submissions"]
---

# Search submissions across forms

`GET /v1/submissions`

## Request

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

Searches the 25 most recently active forms this key can read and returns the matches with the form each one came from.

Takes the same filters as a form's own list. Matches come grouped by form, and the response carries `complete: false` when the search did not reach every form or every match; narrow it with form_ids, team_id or a date range.

For one form, use its own list, which pages through everything with a cursor.

## 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
- `fields` string
- `team_id` string
- `form_ids` string

## Response `200`

- SubmissionSearchList
  - `data` SubmissionResource[], required: Matches across the forms searched, each carrying its form_id.
    - `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
  - `forms_searched` number, required: How many of forms_matched were read before the search stopped.
  - `forms_matched` number, required: Forms picked for the search: the ones the key can read that matched form_ids, at most 25.
  - `complete` boolean, required: False when the search did not reach every form or every match. Narrow it with form_ids, a date range or team_id.

## 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.
- `429`: Too many searches at once for this key.

---

[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)