Create an embed session
Returns a short-lived URL to load in an iframe, tied to the externalUserId you supply.
HTTP request
POST https://www.asqiro.com/api/v1/surveys/{id}/embed-sessions
An API key created by a workspace member who can edit. A viewer's key answers 403.
Path parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | The survey id, as returned by the surveys endpoints.Required |
Request body
| Parameter | Type | Description |
|---|---|---|
| externalUserId | string | Your own identifier for the person taking the survey. It is stored on the resulting response and included in the response.completed event.Required · Maximum length: 256 characters |
Response body
| Field | Type | Description |
|---|---|---|
| embedUrl | string | One-time URL to load in an iframe for this user. |
| expiresAt | string (ISO 8601) | When the URL stops working. |
Note The survey must be published. Calling this for a draft or closed survey answers 400 with the code invalid_request.
Note The URL is valid for one hour and is meant to be created per user, per visit. Create it server-side when you render the page, not in advance.
Errors
- unauthorized · 401 · The API key is missing, malformed, deleted, or its creator lost workspace access. Check the Authorization header, then the key itself.
- forbidden · 403 · The key is valid but lacks the access this call needs - most often a read-only key attempting a write.
- not_found · 404 · No survey with that id is reachable by this key. A survey in another workspace answers the same way as one that does not exist.
- invalid_request · 400 · The request body or a parameter was missing or malformed. Fix the request; retrying it unchanged will fail again.
- plan_upgrade_required · 403 · The workspace owner's plan does not include API access. Upgrading the plan restores it; retrying will not.
- rate_limited · 429 · Too many requests. The Retry-After response header carries the number of seconds to wait.
Example request
bash
curl -X POST "https://www.asqiro.com/api/v1/surveys/s_7t2qk8wvbf31/embed-sessions" \
-H "Authorization: Bearer $ASQIRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"externalUserId":"user_8812"}'Returns 201 on success.
json
{
"embedUrl": "https://www.asqiro.com/f/s_7t2qk8wvbf31?embed=1&embedSession=lM3q...",
"expiresAt": "2026-08-13T11:24:08.512Z"
}