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

# Submissions API

> Retrieve and manage form submissions. Each submission contains the user's responses and metadata.

Retrieve and manage form submissions. Each submission contains the user's responses and metadata.

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/forms/{form_id}/submissions` | List submissions for a form (`submissions:read`) |
| `PATCH` | `/v1/forms/{form_id}/submissions/{id}` | Change answers on a submission (`submissions:write`) |
| `DELETE` | `/v1/forms/{form_id}/submissions/{id}` | Delete a submission and its uploaded files (`submissions:delete`, workspace admins only) |

## Query Parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Results per page (default: 20, max: 100) |
| `since` | string | Filter submissions after this ISO 8601 date |
| `until` | string | Filter submissions before this ISO 8601 date |
| `status` | string | Filter by status: completed or partial |

## Example Response

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

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "fields": {
        "email": "user@example.com",
        "message": "Hello, I have a question..."
      },
      "status": "completed",
      "submitted_at": "2024-01-15T14:30:00Z",
      "metadata": {
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0...",
        "device_type": "desktop",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "spring_sale"
      }
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}
```

## Update a Submission

`PATCH /v1/forms/{form_id}/submissions/{id}`

`fields` is merged into the stored answers: the keys you send are overwritten and the rest are kept. Send `expected_updated_at` (the submission's `updated_at`) to have the change refused with `409 conflict` if someone edited the submission since you read it.

```json theme={null}
{
  "fields": { "company": "Acme", "phone": "+1 555 0100" },
  "expected_updated_at": "2026-10-27T14:30:00.000Z"
}
```

Returns the updated submission: `{ "data": { "id", "fields", "status", "submitted_at", "updated_at" } }`. Viewers can't update submissions.

## Delete a Submission

`DELETE /v1/forms/{form_id}/submissions/{id}`

Deletes the submission and the files uploaded with it. Only workspace admins can delete submissions, as in the dashboard. Returns `{ "data": { "id", "deleted": true } }`. If the files can't all be removed, the submission is kept and the request answers `503`: files already removed stay removed, and a retry removes the rest. If a stored file path fails Orbit's safety check, nothing is removed, the submission is kept and the request answers `500`; contact support to have it cleared.

[Next: Scheduling API](https://docs.useorbitcrm.ai/developers/api/scheduling.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.