Skip to documentation

Forms and responses API reference

Understand form management, published-form discovery and authenticated response submission.

Updated Read as Markdown

Two API families

Use the management API to build forms and review results. Use the published-form API to discover a form and submit answers from a trusted integration.

Base path Purpose Credential
/organizations/ORG_ID/feedback-pages Drafts, settings, questions, responses and sharing Organization-wide key, supported personal key or OAuth; scopes and role apply
/v1/organizations/ORG_ID/feedback-pages Published-form list, form structure and response submission Organization key in X-Pollenate-Key or OAuth Bearer token; no personal keys or browser-session JWTs

A form's private visibility controls who can manage it and read its results inside Pollenate. It does not require respondents to sign in when using its published link.

Build a draft

bash
curl https://api.pollenate.dev/organizations/ORG_ID/feedback-pages \
  -H "X-Pollenate-Key: $POLLENATE_WRITE_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "brandId": "BRAND_ID",
    "title": "Onboarding feedback",
    "status": "draft",
    "questions": [
      { "type": "stars", "prompt": "How easy was setup?", "required": true, "sortOrder": 0 },
      { "type": "text", "prompt": "What could we improve?", "sortOrder": 1 }
    ]
  }'

The response is 201 with id, slug and shortCode. Read the form to obtain generated question IDs. Review it before publishing.

Management method and suffix Action
GET /, GET /PAGE_ID List visible forms or read one with its questions
POST / Create a draft or published form
PUT /PAGE_ID Update supplied settings; status: "published" opens the form
POST /PAGE_ID/clone Copy into an accessible brand
POST /PAGE_ID/questions Add a question
PUT /PAGE_ID/questions/QUESTION_ID Update a question
PUT /PAGE_ID/questions-replace Replace the whole ordered set
GET /PAGE_ID/responses Read submitted answers; limit and returned cursor paginate
GET /PAGE_ID/stats Read aggregate form results
GET/POST /PAGE_ID/shares Inspect sharing or share a private form by member email

An organization key generally needs read to inspect forms/results and write to create/update. OAuth distinguishes forms:read, forms:write and responses:read; see MCP permissions for ownership limits. Organization keys cannot access private form results or create person-owned private forms.

Replacing questions can reuse old IDs and answers by prompt match and then remaining order; it can delete unmatched questions and answers. For a different survey, clone or create a new form instead of relabeling collected answers.

Discover a published form

GET /v1/organizations/ORG_ID/feedback-pages accepts brandId, limit (default 50, maximum 100) and offset. It lists published forms visible to the credential, with pagination metadata. Required scope: forms:read, list or read (or admin).

GET /v1/organizations/ORG_ID/feedback-pages/PAGE_ID returns settings and ordered question IDs. It can read a visible form in any status, so check status before offering it to respondents.

Submit answers from your server

bash
curl https://api.pollenate.dev/v1/organizations/ORG_ID/feedback-pages/PAGE_ID/responses \
  -H "X-Pollenate-Key: $POLLENATE_RESPONSE_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "source": "support-workflow",
    "channel": "web",
    "externalRespondentId": "EXTERNAL_REFERENCE",
    "answers": [
      { "questionId": "RATING_QUESTION_ID", "score": 4 },
      { "questionId": "TEXT_QUESTION_ID", "textValue": "An example would help." }
    ]
  }'

Required scope is responses:write, write or collect (or admin). This authenticated endpoint does not require Turnstile. The browser form uses a separate public submission flow; keep trusted response credentials on your server.

Each answer uses questionId and the applicable score, textValue (up to 5,000 characters) or multiValues array. Contact fields and externalMetadata are optional. Question IDs must belong to the form; required questions must be included. File-upload and voice questions cannot be answered through this API. Display-only content/section questions do not create answers.

Expect 400 for invalid answers, 403 for insufficient scope or closed live submissions, 404 for missing/inaccessible forms, and 409 when the form is not published. Writes are not idempotent: a retried request can create another response. Private-form responses do not fire organization automation rules.