Insert

post

https://{host}/v2/surveys/{surveyId}/responses

Inserts a survey response programmatically; set status to completed, partial, or disqualified. Available on selected plans only — contact SmartSurvey Support if you receive 403. See the Inserting Responses guide for question-type examples.

If you are using the Organisation Hierarchy feature, to assign a response to an entity within the hierarchy, supply either entity_id or entity_unique_id (not both); the entity must be active and belong to your organisation.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

surveyId

int32

required

The survey id to insert the response into

Query Params

return

string

Defaults to minimal

How much of the inserted response to return: full (pages/questions/answers with labels), minimal (just the new id — default), or none (empty body, Location header only)

Body Params

Request DTO for inserting a survey response (completed or partial). Answers are grouped by question
(mirroring the GET shape) and flattened into the insert service's per-cell input.

status

string

required

length ≥ 1

The outcome to record: completed, partial or disqualified.

tracking_link_id

int32 | null

The tracking link the response is attributed to; omit to use the survey's default tracking link. It must
be one of this survey's tracking links, otherwise the request is rejected.

translation_id

int32

The SurveyTranslationId (the unambiguous translation/language identifier) to record the response
against. Omit (or 0) to use the tracking link's default translation, which itself defaults to the survey's
default language. A free-text language code isn't accepted because one code can map to several
translations. It must resolve for this survey — one of its own translations or a shared built-in
language template — otherwise the request is rejected.

unique_id

string | null

An optional caller-supplied unique id for the response.

entity_id

int32 | null

The numeric id of the entity to assign to this response. Supply either this or
entity_unique_id, not both. The entity must be active and belong to your organisation.

entity_unique_id

string | null

The customer-facing unique code of the entity to assign to this response. Supply either this or
entity_id, not both. The entity must be active and belong to your organisation.

date_started

date-time | null

When the response was started (optional; defaults to the time of insert). Useful when importing historical responses.

date_ended

date-time | null

When the response was completed (optional; defaults to the time of insert). Useful when importing historical responses.

generate_save_and_continue_link

boolean

For a partial response, whether to generate and return a save-and-continue link.

completion_actions

string | null

Which completion side-effects to run for a completed response: all (default — full pipeline),
no_email (everything except notification + trigger emails), or none (finalise with no
emails, webhooks, integrations or AI — typically for imports). Omit for all.

questions

array of objects | null

The answers, grouped by question.

questions

variables

array of objects | null

The survey variables to seed, as name/value pairs.

variables

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201The inserted response

400Request validation errors

403Forbidden

404Survey not found

409The response validated but could not be persisted (e.g. usage balance consumption failed); nothing was stored