Public runtime API

The public runtime API is what the <forms-engine> web component talks to. It is designed to be internet-facing: unguessable response ids, per-questionnaire allowed-origin checks, input size caps, and per-IP rate limits on mutating endpoints. You normally never call it yourself — the embed does — but it is documented for debugging and for building custom clients.

All endpoints are unauthenticated; the responseId is the only credential a respondent session holds. See the security posture for what that implies.

This page is generated from the backend’s OpenAPI document (download the raw spec).

GET /public/v1/geocode

Address autocomplete proxy, backed by Photon. The embed never talks to the geocoder directly.

Parameter	In	Type	Required
q	query	string	no
country	query	string	no
limit	query	integer	no
Origin	header	string	no

Response: 200 OK — array of GeocodeSuggestion

GET /public/v1/questionnaires/{publicId}/live

Fetch the currently published version of a questionnaire — the definition the embed renders.

Parameter	In	Type	Required
publicId	path	string	yes
Origin	header	string	no

Response: 200 OK — LiveQuestionnaire

GET /public/v1/questionnaires/{publicId}/ref-status

Check whether an external reference has already completed this questionnaire. Returns only NONE or COMPLETED — never a responseId or answers.

Parameter	In	Type	Required
publicId	path	string	yes
ref	query	string	yes
Origin	header	string	no

Response: 200 OK — RefStatus

POST /public/v1/questionnaires/{publicId}/responses

Start a respondent session. Returns the responseId that identifies this response from here on.

Parameter	In	Type	Required
publicId	path	string	yes
Origin	header	string	no

Request body (application/json): CreateResponseRequest

Response: 201 Created — CreateResponseResult

GET /public/v1/responses/{responseId}

Re-fetch an in-progress response (answers, position, and the pinned definition version) — used to resume a session after a page refresh.

Parameter	In	Type	Required
responseId	path	string	yes
Origin	header	string	no

Response: 200 OK — ResponseRehydration

PATCH /public/v1/responses/{responseId}

Save answers and the current position. Called by the embed as the respondent moves through the form.

Parameter	In	Type	Required
responseId	path	string	yes
Origin	header	string	no

Request body (application/json): PatchResponseRequest

Response: 200 OK

POST /public/v1/responses/{responseId}/complete

Mark the response as completed. After this, the response can no longer be modified.

Parameter	In	Type	Required
responseId	path	string	yes
Origin	header	string	no

Response: 200 OK

POST /public/v1/responses/{responseId}/files

Upload a file for a FILE_UPLOAD question on an in-progress response. Content is verified server-side (magic bytes), not trusted from the filename.

Parameter	In	Type	Required
responseId	path	string	yes
questionCode	query	string	yes
Origin	header	string	no

Request body (multipart/form-data, optional): object

Field	Type	Required
file	binary	yes

Response: 201 Created — FileReference

DELETE /public/v1/responses/{responseId}/files/{fileId}

Remove a previously uploaded file from an in-progress response.

Parameter	In	Type	Required
responseId	path	string	yes
fileId	path	string	yes
Origin	header	string	no

Response: 204 No Content

Data model

Condition

Field	Type
source	string
questionCode	string
subField	string
operator	string
value	any

CreateResponseRequest

Field	Type
versionNumber	integer
externalRef	string

CreateResponseResult

Field	Type
responseId	string

Definition

Field	Type
schemaVersion	integer
steps	array of Step
tabs	array of Tab
questions	array of Question

FileReference

Field	Type
fileId	string
fileName	string
size	integer (int64)
contentType	string

GeocodeSuggestion

Field	Type
line1	string
city	string
state	string
postalCode	string
country	string
label	string

LiveQuestionnaire

Field	Type
publicId	string
name	string
versionNumber	integer
definition	Definition
submissionPolicy	string

PatchResponseRequest

Field	Type
answers	object (free-form)
lastPosition	PositionDto

PositionDto

Field	Type
stepId	string
tabId	string

Question

Field	Type
id	string
code	string
sectionTitle	string
prompt	string
type	string
width	string
typeConfig	object (free-form)
visibility	RuleConfig
requirement	RuleConfig

RefStatus

Field	Type
status	string

ResponseRehydration

Field	Type
status	string
versionNumber	integer
answers	object (free-form)
lastPosition	PositionDto
definition	Definition
submissionPolicy	string

Rule

Field	Type
combinator	string
conditions	array of Condition

RuleConfig

Field	Type
mode	string
rule	Rule

Step

Field	Type
id	string
title	string
visibility	RuleConfig
requirement	RuleConfig
tabs	array of Tab
questions	array of Question

Tab

Field	Type
id	string
title	string
visibility	RuleConfig
requirement	RuleConfig
questions	array of Question