Documentation

Forms

Forms cover surveys and general-purpose forms as one resource — an ordered list of fields with no correct-answer concept, unlike Quizzes.

Managing a form (create/read/update/delete, and reading its submissions) requires your API key and is scoped to your own forms. Submitting a form is public — see Form Submissions.

Method	Endpoint	Description
POST	`/forms`	Create a form
GET	`/forms`	List all of your forms
GET	`/forms/identifier/{identifier}`	Get one of your forms by its identifier
GET	`/forms/{form}`	Get one of your forms by ID
PATCH	`/forms/{form}`	Update a form (PUT also accepted)
DELETE	`/forms/{form}`	Delete a form (also deletes its fields and submissions)

POST /forms API key

Create a form

Field	Type	Rules
identifier	string	Optional, same rules as Poll's identifier — unique per account. Generated from `title` if omitted.
title	string	Required, max 255
description	string	Optional
metadata	object	Optional, freeform — same as Poll's `metadata`
site_id	integer	Optional, same rules as Poll's `site_id`
requires_captcha	boolean	Optional, same rules as Poll's `requires_captcha` — see Form Submissions.
is_closed	boolean	Optional, same rules as Poll's `is_closed` — see Form Submissions.
response_limit	integer	Optional, nullable, minimum 1, same rules as Poll's `response_limit`.
fields	array	Required, at least 1
fields[].label	string	Required, max 255
fields[].type	string	Required, one of: `text`, `textarea`, `number`, `email`, `date`, `single_choice`, `multi_choice`, `rating`
fields[].required	boolean	Optional, defaults to `true`
fields[].options	array of strings	Required for `single_choice`/`multi_choice` (at least 2, each unique within the field); rejected for every other type

rating is a fixed 1-5 scale.

REQUEST

curl -X POST https://qnaapi.com/api/v1/forms \
  -H "X-API-Key: qna_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "customer-feedback",
    "title": "Customer Feedback",
    "fields": [
      { "label": "Your name", "type": "text" },
      { "label": "Email (optional)", "type": "email", "required": false },
      { "label": "How did you hear about us?", "type": "single_choice", "options": ["Search", "Friend", "Ad"] },
      { "label": "How would you rate us?", "type": "rating" }
    ]
  }'

201 CREATED

{
  "data": {
    "id": 1,
    "identifier": "customer-feedback",
    "title": "Customer Feedback",
    "description": null,
    "metadata": null,
    "site_id": null,
    "requires_captcha": false,
    "is_closed": false,
    "response_limit": null,
    "is_accepting_responses": true,
    "fields": [
      { "id": 1, "label": "Your name", "type": "text", "options": null, "required": true, "position": 0 },
      { "id": 2, "label": "Email (optional)", "type": "email", "options": null, "required": false, "position": 1 },
      { "id": 3, "label": "How did you hear about us?", "type": "single_choice", "options": ["Search", "Friend", "Ad"], "required": true, "position": 2 },
      { "id": 4, "label": "How would you rate us?", "type": "rating", "options": null, "required": true, "position": 3 }
    ],
    "created_at": "2026-08-20T15:00:00.000000Z",
    "updated_at": "2026-08-20T15:00:00.000000Z"
  }
}

is_accepting_responses is read-only and computed on every response — false whenever is_closed is true or the form's submission count has reached response_limit. Toggle is_closed/response_limit instead of trying to set it directly.

GET /forms, /forms/{form}, /forms/identifier/{identifier} API key

List / get by ID / get by identifier

Same shape as the equivalent Poll/Quiz endpoints, scoped to your own forms.

REQUEST

curl -H "X-API-Key: qna_..." https://qnaapi.com/api/v1/forms

PATCH /forms/{form} API key

Update a form

Every field is optional. fields can be replaced using the same shape and validation rules as create — but only while the form has zero submissions. site_id, requires_captcha, is_closed, and response_limit can be changed at any time.

REQUEST

curl -X PATCH https://qnaapi.com/api/v1/forms/1 \
  -H "X-API-Key: qna_..." \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey" }'

Once someone has submitted a form, sending fields in an update is rejected (422), for the same reason Poll options and Quiz questions lock after their first response: changing them would silently invalidate existing answers. Delete and recreate the form if its fields need to change after that point.

DELETE /forms/{form} API key

Delete a form

REQUEST

curl -X DELETE -H "X-API-Key: qna_..." https://qnaapi.com/api/v1/forms/1

204 No Content on success. Cascades — fields and submissions are removed too.