---
title: "List Form Submissions"
method: POST
path: "/forms/{id}/submissions/list"
tags: ["Forms > submissions"]
---

# List Form Submissions

`POST /forms/{id}/submissions/list`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/forms/{id}/submissions/list`
- Auth: API key in header `PINNACLE-API-KEY`

Paginated list of completed submissions for a form, newest first. Each row includes the submitted `data` keyed by field `key`, the sender/recipient, IP, user-agent, and timestamps.

## Path parameters

- `id` string, required

## Request body

- ListFormSubmissionsRequest: Pagination for `POST /forms/{id}/submissions/list`. Newest submissions first.
  - `pageIndex` integer: Zero-based page index.
  - `pageSize` integer: Number of submissions to return in a single page. Max 100.

## Response `200`

Paginated list of submissions.

- ListFormSubmissionsResponse: Paginated page of submissions for a form.
  - `data` FormSubmission[], required: Submissions on this page, newest first.
    - `id` string, required: Submission id (starts with `fsub_`).
    - `url` string, required: Public submission URL (`https://forms.pinnacle.sh/{submission_id}`) — the unguessable credential used by the recipient to fill out the form.
    - `form_id` string, required: Id of the form this submission belongs to (starts with `form_`).
    - `from` string, nullable, required: Sender identifier — E.164 phone number or RCS agent id. Null if the sender could no longer be resolved (e.g. the phone number or agent was deleted after the submission).
    - `to` string, nullable, required: Recipient phone number (E.164). Null for URL-only sends (`to` was omitted at send time).
    - `data` object, nullable, required: Submitted answers keyed by field `key`. Null if the submission has not been completed yet. Each value's shape depends on the field type: - `text`, `email`, `phone`, `url`, `textarea`, `select`, `radio` → string - `number` → number - `checkbox` (single) → boolean - `checkbox` (multi), `multiselect` → array of strings - Skipped optional field → null
    - `ip_address` string, nullable, required: IP address the submission was POSTed from. Null for pending submissions.
    - `user_agent` string, nullable, required: User-Agent header of the browser that submitted the form. Null for pending submissions.
    - `submitted_at` string, date-time, nullable, required: Timestamp of completion. Null for pending submissions; updated on each edit of a `can_update=true` submission.
    - `created_at` string, date-time, required: Timestamp of when the submission URL was minted.
  - `hasMore` boolean, required: True if there are more pages after this one. Fetch the next page by incrementing `pageIndex`.
  - `count` integer, required: Number of submissions returned in `data`.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)