Forms and responses API reference
Understand form management, published-form discovery and authenticated response submission.
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
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
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.