Embed Surveys

Hosted embeds are the fastest way to get a survey into your product when you do not need to own the full rendering pipeline.

Use embeds when you want the shortest path to a live survey and are comfortable passing theme or identity context in the URL on each load.

Fastest working example

Use the embed URL in an iframe or open it in a new window. Replace YOUR_API_KEY with your app's public API key and SURVEY_ID with the survey you want to load.

<iframe
  src="https://getuserfeedback.com/embed/YOUR_API_KEY/SURVEY_ID"
  title="Survey"
  width="100%"
  height="400"
></iframe>

Or as a direct link:

https://getuserfeedback.com/embed/YOUR_API_KEY/SURVEY_ID

If you want the initial color scheme to be server-rendered, append it as a path segment:

https://getuserfeedback.com/embed/YOUR_API_KEY/SURVEY_ID/dark

Each request is stateless. Theme and identity come from the URL you send on that load.

What you can control

Identity parameters are optional and passed as URL query string, for example ?user_id=123. Color scheme can be passed either as a path segment or as the legacy color_scheme query parameter.

Color scheme

Input	Values	Default	Description
`/:colorScheme`	`light`, `dark`, `system`	`light`	Preferred path-based format.
`?color_scheme=`	`light`, `dark`, `system`	`light`	Legacy query-string format. Still supported for compatibility, but path-based embeds are preferred.

Examples:

/embed/YOUR_API_KEY/SURVEY_ID — light theme
/embed/YOUR_API_KEY/SURVEY_ID/light — explicit light theme
/embed/YOUR_API_KEY/SURVEY_ID/dark — dark theme, server-rendered
/embed/YOUR_API_KEY/SURVEY_ID/system — follow system light and dark
/embed/YOUR_API_KEY/SURVEY_ID?color_scheme=dark — legacy dark theme
/embed/YOUR_API_KEY/SURVEY_ID?color_scheme=system — legacy system theme

If both the path segment and query parameter are provided, the path segment wins.

Identities

Pass user or device identities when the survey should associate the response with a known user. Use the same query parameter names as the share link.

Parameter	Description
`user_id`	Your stable user identifier.
`anonymous_id`	Anonymous or session ID.
`email`	User email (maps to `traits.email`).
`phone`	User phone (maps to `traits.phone`).
`advertising_id`	Device advertising ID.
`device_id`	Device ID.
`device_token`	Device token (e.g. push).

You can combine multiple identity parameters in one URL. Values are URL-encoded as needed.

Example with identities and color scheme:

/embed/YOUR_API_KEY/SURVEY_ID/dark?user_id=user_abc123&email=user%40example.com

If the survey requires identity for routing or analytics, include at least one valid identifier up front.

Production notes

Treat the embed URL as configuration, not content. Build it intentionally from your app key, survey ID, color scheme, and identity state.
Use the path-based color scheme when you want the initial render to look right immediately, especially in dark mode.
If your product already knows the user, pass that identity up front so responses land in the right context.
If your security perimeter requires JWT auth, read JWT Auth before rollout.