# Submissions · Management API

> Management API reference for submissions: GET /sites/{id}/forms/{formId}/submissions, GET /sites/{id}/forms/{formId}/submissions/{submissionId}, PATCH /sites/{id}/forms/{formId}/submissions/{submissionId}.

> Markdown version of https://kanorio.com/en/developers/management-api/submissions. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://app.kanorio.com/api/v1` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List submissions

`GET /sites/{id}/forms/{formId}/submissions`

- Stability: beta
- Permission: `marketing:view`
- Rate limit: default (120/minute per token)
- MCP tool: `submissions_list`

List submissions of one form, newest first, with answers keyed by field id. Filter by status, full-text query and recent days. Attachments are returned as metadata only; downloading files and exporting CSV are not available to agents. attachments maps attachment ids used in this page's answers to their metadata. Errors: FORBIDDEN, FORM_NOT_FOUND, INVALID_CURSOR.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `formId` | path | string | yes | Form id. Get it from forms.list. |
| `limit` | query | integer | no | Maximum number of items to return, 1–100. Defaults to 20. |
| `cursor` | query | string | no | Opaque cursor from the previous page's nextCursor. Omit for the first page. |
| `status` | query | "ALL" \| "NEW" \| "READ" \| "SPAM" \| "ARCHIVED" | no | — |
| `q` | query | string | no | Full-text search in answers. |
| `days` | query | integer | no | Only submissions from the last N days in the website's timezone; one of 1, 7, 30, 90. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | — |
| `data[].id` | string | yes | — |
| `data[].status` | string | yes | NEW, READ, SPAM or ARCHIVED. |
| `data[].submittedAt` | string | yes | — |
| `data[].contactId` | string \| null | yes | — |
| `data[].display` | string \| null | yes | Name, else email, else phone; null for anonymous forms. |
| `data[].answers` | object | yes | Keyed by field id; file fields hold attachment ids (see attachments). |
| `hasMore` | boolean | yes | True when another page exists; pass nextCursor to fetch it. |
| `nextCursor` | string \| null | yes | Cursor for the next page, or null on the last page. |
| `attachments` | object | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `FORM_NOT_FOUND` | 404 | — |
| `INVALID_CURSOR` | 400 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/forms/{formId}/submissions?limit=20" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "data": [
    {
      "id": "sub_example01",
      "status": "NEW",
      "submittedAt": "2026-10-06T08:00:00.000Z",
      "contactId": "contact_example01",
      "display": "Alex Chen",
      "answers": {
        "name": "Alex Chen",
        "email": "customer@example.com",
        "message": "I'd like to pre-order a birthday cake for Saturday."
      }
    }
  ],
  "attachments": {},
  "hasMore": false,
  "nextCursor": null
}
```

### Retrieve a submission

`GET /sites/{id}/forms/{formId}/submissions/{submissionId}`

- Stability: beta
- Permission: `marketing:view`
- Rate limit: default (120/minute per token)
- MCP tool: `submissions_get`

Get one submission of a form with its answers and attachment metadata. Errors: FORBIDDEN, SUBMISSION_NOT_FOUND.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `formId` | path | string | yes | Form id. Get it from forms.list. |
| `submissionId` | path | string | yes | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `submission` | object | yes | — |
| `submission.id` | string | yes | — |
| `submission.status` | string | yes | NEW, READ, SPAM or ARCHIVED. |
| `submission.submittedAt` | string | yes | — |
| `submission.contactId` | string \| null | yes | — |
| `submission.display` | string \| null | yes | Name, else email, else phone; null for anonymous forms. |
| `submission.answers` | object | yes | Keyed by field id; file fields hold attachment ids (see attachments). |
| `attachments` | object | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `SUBMISSION_NOT_FOUND` | 404 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/forms/{formId}/submissions/{submissionId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "submission": {
    "id": "sub_example01",
    "status": "NEW",
    "submittedAt": "2026-10-06T08:00:00.000Z",
    "contactId": "contact_example01",
    "display": "Alex Chen",
    "answers": {
      "name": "Alex Chen",
      "email": "customer@example.com",
      "message": "I'd like to pre-order a birthday cake for Saturday."
    }
  },
  "attachments": {}
}
```

### Update status

`PATCH /sites/{id}/forms/{formId}/submissions/{submissionId}`

- Stability: beta
- Permission: `marketing:manage`
- Rate limit: default (120/minute per token)
- MCP tool: `submissions_update_status`

Update the status of a form submission (NEW, READ, SPAM, or ARCHIVED). Unmarking a SPAM submission promotes it to a contact if the form collects identity. Errors: FORBIDDEN, SUBMISSION_NOT_FOUND, VALIDATION.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `formId` | path | string | yes | Form id. Get it from forms.list. |
| `submissionId` | path | string | yes | Submission id from submissions.list. |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | "NEW" \| "READ" \| "SPAM" \| "ARCHIVED" | yes | Target submission status. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Submission id. |
| `status` | "NEW" \| "READ" \| "SPAM" \| "ARCHIVED" | yes | Updated submission status. |
| `promoted` | boolean | yes | True when unmarking spam promoted the submission into a Contact. |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `SUBMISSION_NOT_FOUND` | 404 | — |
| `VALIDATION` | 400 | — |

```bash
curl -X PATCH "https://app.kanorio.com/api/v1/sites/{id}/forms/{formId}/submissions/{submissionId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"READ"}'
```

```json
{
  "id": "sub_example01",
  "status": "READ",
  "promoted": false
}
```