Answer JSON shapes

Responses store answers as one flat map keyed by question code, with typed values. This is what you’ll see in Mongo, in the management API’s response listing, and (in flattened form) in CSV export.

A complete example:

{
  "food1": "pizza",
  "toppings": ["Mushroom", "Onion"],
  "visitDate": "2026-09-14",
  "partySize": 4,
  "budgetPct": 12.5,
  "zeroCount": 0,
  "newsletter": false,
  "homeAddr": {
    "country": "US",
    "line1": "12 Main St",
    "line2": "",
    "city": "Woodbury",
    "state": "NJ",
    "postalCode": "08096"
  },
  "resume": [
    {
      "fileId": "f_9c1e4a7b2d3f40518a6c9e0d1b2a3c4d",
      "fileName": "Josh_Resume.pdf",
      "size": 482113,
      "contentType": "application/pdf"
    }
  ]
}

Shape by type

Question type	Value	Notes
Text box, Email, Phone	string	Trimmed; empty stores nothing
Radio, Dropdown	string	The selected option’s label
Checkboxes	array of strings	Option labels, in option order; never empty (key removed instead)
Date	string "YYYY-MM-DD"	No time, no timezone
Number	JSON number	0 is a valid answer; never a string
Toggle	JSON boolean	false is a valid answer; untouched = key absent
Address	flat object	Exactly the enabled sub-fields as keys; codes for country/US state; untouched enabled fields as ""
File upload	array of file references	Always an array, even for single-file questions
Display text	—	Never present

A file reference has exactly four keys — fileId, fileName, size, contentType — with contentType being the server-verified type. Storage keys never appear in answers or anywhere else in the API.

The general principle: absence means unanswered. There are no empty strings, empty arrays, or nulls standing in for “no answer” (the embed never produces them; note the server’s shape validation doesn’t forbid an empty array from a hand-written client).

What the server validates

The PATCH endpoint validates shape and size, not meaning — it doesn’t check answers against the questionnaire definition (the renderer does that; server-side re-validation is a roadmap item). The rules:

• Keys must look like question codes (start with a letter; letters, digits, _, -; max 64 chars). At most 500 keys.
• Values must be: a string, a finite number, a boolean, an array (≤ 100 elements) of all-strings or all-file-references (never mixed), or a flat object (≤ 20 keys) with string values.
• Size caps: 10 KB per answer, 256 KB for the whole map.
• null is rejected with an explicit message — omit the key to clear an answer.
• File references must have exactly the four keys above.

Violations return 400 {"message": "invalid answers", "errors": [...]} with every problem listed at once.

Reading the data downstream

• Join on question code + versionNumber. A response is only guaranteed interpretable against the version it’s pinned to — codes and options can differ across versions.
• Choice answers are labels; if you rename options between versions, segment by version before aggregating.
• The file bytes live in your storage backend; fetch them through the management download endpoint, keyed by the fileId in the answer.