API リファレンス

Submissions

Management API: GET /sites/{id}/forms/{formId}/submissions, GET /sites/{id}/forms/{formId}/submissions/{submissionId}, PATCH /sites/{id}/forms/{formId}/submissions/{submissionId}

このページは英語のみです。API リファレンス、Webhook イベント、変更履歴は、コード内のフィールド名やエラーコードと揃えるため英語で提供しています。

Base URL https://app.kanorio.com/api/v1Errors Pagination

List submissions

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

betamarketing:viewdefault (120/minute per token)

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

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
formIdstring · pathrequired
Form id. Get it from forms.list.
limitinteger · query
Maximum number of items to return, 1–100. Defaults to 20.
cursorstring · query
Opaque cursor from the previous page's nextCursor. Omit for the first page.
status"ALL" | "NEW" | "READ" | "SPAM" | "ARCHIVED" · query
qstring · query
Full-text search in answers.
daysinteger · query
Only submissions from the last N days in the website's timezone; one of 1, 7, 30, 90.

Response 200

dataobject[]required
data[].idstringrequired
data[].statusstringrequired
NEW, READ, SPAM or ARCHIVED.
data[].submittedAtstringrequired
data[].contactIdstring | nullrequired
data[].displaystring | nullrequired
Name, else email, else phone; null for anonymous forms.
data[].answersobjectrequired
Keyed by field id; file fields hold attachment ids (see attachments).
hasMorebooleanrequired
True when another page exists; pass nextCursor to fetch it.
nextCursorstring | nullrequired
Cursor for the next page, or null on the last page.
attachmentsobjectrequired

Errors

FORBIDDEN 403
FORM_NOT_FOUND 404
INVALID_CURSOR 400

MCP tool submissions_list

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

Response

{
  "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}

betamarketing:viewdefault (120/minute per token)

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

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
formIdstring · pathrequired
Form id. Get it from forms.list.
submissionIdstring · pathrequired

Response 200

submissionobjectrequired
submission.idstringrequired
submission.statusstringrequired
NEW, READ, SPAM or ARCHIVED.
submission.submittedAtstringrequired
submission.contactIdstring | nullrequired
submission.displaystring | nullrequired
Name, else email, else phone; null for anonymous forms.
submission.answersobjectrequired
Keyed by field id; file fields hold attachment ids (see attachments).
attachmentsobjectrequired

Errors

FORBIDDEN 403
SUBMISSION_NOT_FOUND 404

MCP tool submissions_get

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

Response

{
  "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}

betamarketing:managedefault (120/minute per token)

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

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
formIdstring · pathrequired
Form id. Get it from forms.list.
submissionIdstring · pathrequired
Submission id from submissions.list.

Request body

status"NEW" | "READ" | "SPAM" | "ARCHIVED"required
Target submission status.

Response 200

idstringrequired
Submission id.
status"NEW" | "READ" | "SPAM" | "ARCHIVED"required
Updated submission status.
promotedbooleanrequired
True when unmarking spam promoted the submission into a Contact.

Errors

FORBIDDEN 403
SUBMISSION_NOT_FOUND 404
VALIDATION 400

MCP tool submissions_update_status

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"}'

Response

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