Submissions

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

{
  "id": 987,
  "formId": 123,
  "formData": { "Name": "Jane Doe", "Email": "[email protected]" },
  "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.

curl https://api.sorraia.app/v1/forms/123/submissions \
  -H "Authorization: Bearer sor_live_xxxxxxxx"

const result = await sorraia.submissions.listFormSubmissions({ id: 123 });

Get a submission

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

curl https://api.sorraia.app/v1/submissions/987 \
  -H "Authorization: Bearer sor_live_xxxxxxxx"

const submission = await sorraia.submissions.getSubmission({ id: 987 });

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

curl -X POST https://api.sorraia.app/v1/forms/123/submissions \
  -H "Authorization: Bearer sor_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "formData": { "Name": "Jane", "Email": "[email protected]" } }'

const submission = await sorraia.submissions.createSubmission({
  id: 123,
  body: { formData: { Name: "Jane", Email: "[email protected]" } },
});

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.

curl -X POST https://api.sorraia.app/v1/forms/123/submissions \
  -H "Authorization: Bearer sor_live_xxxxxxxx" \
  -H "Idempotency-Key: order-4567-submission" \
  -H "Content-Type: application/json" \
  -d '{ "formData": { "Name": "Jane" } }'

const submission = await sorraia.submissions.createSubmission({
  id: 123,
  idempotencyKey: "order-4567-submission",
  body: { formData: { Name: "Jane" } },
});

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

Get started

Resources

Integrate

The submission object

List a form’s submissions

Get a submission

Ingest a submission

Idempotency

​The submission object

​List a form’s submissions

​Get a submission

​Ingest a submission

​Idempotency

The submission object

List a form’s submissions

Get a submission

Ingest a submission

Idempotency