# Forms · Management API

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

> Markdown version of https://kanorio.com/en/developers/management-api/forms. 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 forms

`GET /sites/{id}/forms`

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

List this website's online forms with status, availability and submission counts. Errors: FORBIDDEN, INVALID_CURSOR.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `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. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | — |
| `data[].id` | string | yes | — |
| `data[].name` | string | yes | — |
| `data[].status` | string | yes | — |
| `data[].availability` | string | yes | open, paused, closed_by_schedule, full, ... (see FormAvailability). |
| `data[].hasIdentity` | boolean | yes | false = anonymous form (no email/phone field); submissions do not create contacts. |
| `data[].fieldCount` | integer | yes | — |
| `data[].submissionCount` | integer | yes | Non-spam submissions. |
| `data[].unreadCount` | integer | yes | — |
| `data[].updatedAt` | string | yes | — |
| `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. |

**Errors**

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

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

```json
{
  "data": [
    {
      "id": "form_example01",
      "name": "Pre-order form",
      "status": "PUBLISHED",
      "availability": "OPEN",
      "hasIdentity": true,
      "fieldCount": 4,
      "submissionCount": 12,
      "unreadCount": 2,
      "updatedAt": "2026-10-01T02:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

### Retrieve a form

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

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

Get one form including its field definitions and settings (read-only; forms are edited in the console). Errors: FORBIDDEN, FORM_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. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | — |
| `name` | string | yes | — |
| `description` | string \| null | yes | — |
| `status` | string | yes | — |
| `availability` | string | yes | open, paused, closed_by_schedule, full, ... (see FormAvailability). |
| `fields` | object[] | yes | Form field definitions (id, type, label, required, options, contactMapping...). |
| `settings` | object | yes | — |
| `replyEmailEnabled` | boolean | yes | — |
| `submissionCount` | integer | yes | — |
| `createdAt` | string | yes | — |
| `updatedAt` | string | yes | — |

**Errors**

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

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

```json
{
  "id": "form_example01",
  "name": "Pre-order form",
  "description": "Leave your details and we'll confirm your order by email.",
  "status": "PUBLISHED",
  "availability": "OPEN",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "label": "Name",
      "required": true
    },
    {
      "id": "email",
      "type": "email",
      "label": "Email",
      "required": true
    },
    {
      "id": "message",
      "type": "textarea",
      "label": "Message",
      "required": false
    }
  ],
  "settings": {
    "successMessage": "Thanks! We'll get back to you shortly."
  },
  "replyEmailEnabled": true,
  "submissionCount": 12,
  "createdAt": "2026-08-12T03:20:00.000Z",
  "updatedAt": "2026-10-01T02:30:00.000Z"
}
```