> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formitto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submissions

> Read a form's submissions and ingest new ones programmatically.

A **submission** is one set of field values captured by a form — whether from
the embedded widget or ingested through the API.

## The submission object

```json theme={null}
{
  "id": 987,
  "formId": 123,
  "formData": { "Name": "Jane Doe", "Email": "jane@example.com" },
  "sourceDomain": "example.com",
  "createdAt": "2026-05-20T09:30:00.000Z"
}
```

`formData` is a label → value map. `sourceDomain` is the page hostname the
submission came from, or `null` for API-ingested submissions.

## List a form's submissions

`GET /v1/forms/{id}/submissions` — scope `read:submissions`. Paginated
(`page`, `limit`), newest first.

<CodeGroup>
  ```bash curl theme={null}
  curl https://formitto.com/v1/forms/123/submissions \
    -H "Authorization: Bearer fmt_live_xxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  const result = await formitto.submissions.listFormSubmissions({ id: 123 });
  ```
</CodeGroup>

## Get a submission

`GET /v1/submissions/{id}` — scope `read:submissions`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://formitto.com/v1/submissions/987 \
    -H "Authorization: Bearer fmt_live_xxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  const submission = await formitto.submissions.getSubmission({ id: 987 });
  ```
</CodeGroup>

## Ingest a submission

`POST /v1/forms/{id}/submissions` — scope `write:submissions`. Runs the same
pipeline as the embedded widget (webhooks fire, confirmation/owner emails send,
PHI handling applies). Send a `formData` object (max 50 fields, max 50KB
serialized).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://formitto.com/v1/forms/123/submissions \
    -H "Authorization: Bearer fmt_live_xxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "formData": { "Name": "Jane", "Email": "jane@example.com" } }'
  ```

  ```typescript TypeScript theme={null}
  const submission = await formitto.submissions.createSubmission({
    id: 123,
    body: { formData: { Name: "Jane", Email: "jane@example.com" } },
  });
  ```
</CodeGroup>

## Idempotency

To safely retry an ingest without creating duplicates, send an
`Idempotency-Key` header (a client-chosen unique string, ≤256 chars). Within
**24 hours**, a repeat request with the same key replays the original result
(HTTP 200) instead of creating a second submission.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://formitto.com/v1/forms/123/submissions \
    -H "Authorization: Bearer fmt_live_xxxxxxxx" \
    -H "Idempotency-Key: order-4567-submission" \
    -H "Content-Type: application/json" \
    -d '{ "formData": { "Name": "Jane" } }'
  ```

  ```typescript TypeScript theme={null}
  const submission = await formitto.submissions.createSubmission({
    id: 123,
    idempotencyKey: "order-4567-submission",
    body: { formData: { Name: "Jane" } },
  });
  ```
</CodeGroup>

A fresh ingest returns **201**; an idempotent replay returns **200** with the
original submission.