API

Use the HTTP API when you want to collect answers in your own UI or backend and send them to getuserfeedback.com.

Most teams use the widget instead. The API is here for custom flows where you need to resolve a published survey version, collect answers yourself, and submit responses directly.

Available endpoints

Endpoint	Purpose
`GET /api/v1/{apiKey}/flows/{surveyId}`	Resolve the latest published `flowVersionId` for a survey.
`GET /api/v1/{apiKey}/flow_versions/{flowVersionId}`	Fetch the published snapshot for a specific flow version.
`POST /api/v1/{apiKey}/trpc/response.submit`	Submit answers against a published flow version.

Base path and authentication

Base path: /api/v1/{apiKey}/… where {apiKey} is your app's API key.
When user authentication is enabled, send Authorization: Bearer <token> on each request.
When security is disabled, requests work without a token.

Submitting a response

Most API integrations follow this sequence:

Resolve the current published flowVersionId.
Collect the answers in your own UI.
Submit via response.submit.

Example request

curl -X POST \https://getuserfeedback.com/api/v1/YOUR_API_KEY/trpc/response.submit \-H "Content-Type: application/json" \-d '{"flowVersionId": "flv_123","answers": {"question_1": "Very satisfied","question_2": ["fast", "clear"]},"identities": [{ "type": "userId", "value": "user_123" },{ "type": "traits.email", "value": "user@example.com" }]}'

Optional fields

You can also include metadata, context, and flowAssignmentId:

{"flowVersionId": "flv_123","answers": { "question_1": "Very satisfied" },"metadata": {"tags": {"journey_stage": "onboarding","task_type": "report-export"}},"context": {"page": {"path": "/settings/billing","referrer": "/settings"},"locale": "en-AU","userAgent": "Mozilla/5.0"}}

metadata.tags supports flat string values and string arrays:

{"metadata": {"tags": {"error_type": "validation","error_surface": "checkout","selected_modules": ["billing", "reporting"]}}}

For hosted survey links and iframe embeds, you can attach the same response metadata with URL parameters instead. See Response metadata.

For practical limits and guardrails around metadata and submission windows, see Limits.

Success response

{"result": {"data": {"success": true,"responseId": "resp_abc123"}}}

Error response

{"result": {"data": {"success": false,"errors": {"formErrors": ["Flow version not found."]}}}}

Common errors

Flow version not found. — the flowVersionId is unknown or no longer available.
This survey version is no longer accepting responses... — a newer version has been published and the grace window has passed.

When in doubt, resolve the latest published version again before retrying.