# Forms and responses API reference > Understand form management, published-form discovery and authenticated response submission. Canonical URL: https://pollenate.dev/docs/api/forms/ ## 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](/docs/integrations/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.