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 flow version, collect answers yourself, and submit responses directly.

Available endpoints

Base path and identity verification

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

Submitting a response

Most API integrations follow this sequence:

1. Resolve the current published flowVersionId.
2. Fetch that version with ?payload=4 and collect the answers in your own UI.
3. Submit via response.submit, sending the same payload generation.

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","flowVersionPayloadGeneration": "4","answers": {"question_1": "Very satisfied","question_2": ["fast", "clear"]},"identities": [{ "type": "userId", "value": "user_123" },{ "type": "traits.email", "value": "user@example.com" }]}'

flowVersionPayloadGeneration must match the payload generation used to fetch the flow version.

Optional fields

You can also include metadata, context, and flowAssignmentId:

{"flowVersionId": "flv_123","flowVersionPayloadGeneration": "4","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 flow 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, or the survey's live window has closed.
• This survey is not open yet. — the survey's live window has not started, or it has never been published.

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