Answer Formats

This page documents the value formats accepted for submission answers — the Answer and AnswerRef properties of CreateSubmissionAnswerRequest. The required format depends on the field type defined in the form.

📘

Where to find a field's type

Call GET /forms/{id} and look at each field's Type property. The Ref on the field is what you put in the request's Ref.

If you're storing record values instead, see Value formats — same encoding rules, different request shape.

Quick reference

Name

The value is a JSON-encoded string representing an object with first, middle, and last. Include middle only when the field's UseMiddleName is true.

Object shape:

{ "first": "John", "middle": "Michael", "last": "Smith" }

On the wire (note the escaped quotes — this is a string value, not a nested object):

{
  "ref": "100912750",
  "answer": "{\"first\":\"John\",\"middle\":\"Michael\",\"last\":\"Smith\"}"
}

{
  ref: "100912750",
  answer: JSON.stringify({ first: "John", middle: "Michael", last: "Smith" })
}

new CreateSubmissionAnswerRequest
{
    Ref = "100912750",
    Answer = JsonSerializer.Serialize(new { first = "John", middle = "Michael", last = "Smith" })
}

🚧

Common mistake

Sending "answer": { "first": "John", ... } (a nested object) will be rejected. The field is typed as a string — the JSON must be serialised first.

Address

Same encoding rule as Name — the value is a JSON-encoded string.

Object shape:

{
  "address": "123 Main St",
  "city": "Brisbane",
  "state": "QLD",
  "zip": "4000",
  "country": "Australia"
}

On the wire:

{
  "ref": "100912751",
  "answer": "{\"address\":\"123 Main St\",\"city\":\"Brisbane\",\"state\":\"QLD\",\"zip\":\"4000\",\"country\":\"Australia\"}"
}

{
  ref: "100912751",
  answer: JSON.stringify({
    address: "123 Main St",
    city: "Brisbane",
    state: "QLD",
    zip: "4000",
    country: "Australia"
  })
}

All sub-properties except address are optional, but supplying them produces better-rendered documents.

DateTime

Format: yyyy-MM-dd HH:mm (24-hour clock, no timezone — submission timezone comes from SubmissionLocalTime on the parent request).

{ "ref": "100912752", "answer": "2026-05-14 09:30" }

Email

Any RFC-5322 valid email address.

{ "ref": "100912753", "answer": "[email protected]" }

Phone

Free-form. We recommend E.164 (+61412345678) or the locale-formatted variant ((123) 456-7890). The value is not parsed — it is rendered verbatim.

{ "ref": "100912754", "answer": "(123) 456-7890" }

Number and Currency

Digits only, no separators or symbols. For Currency fields, also set CurrencyCode to an ISO 4217 code (AUD, USD, GBP, …).

{ "ref": "100912755", "answer": "123456789", "currencyCode": "AUD" }

Id

Format depends on the jurisdiction configured for the field.

{ "ref": "100912756", "answer": "12 234 678 901" }

Option-based fields (Checkbox, Radio, Select)

Leave Answer empty. Put the option's Ref in AnswerRef.

• Radio / Select — a single option ref: "answerRef": "100912757"
• Checkbox — multiple option refs joined by ;: "answerRef": "100912757;100912758;100912759"

Get option refs from the form definition under the field's Options array.

Linked fields

Leave Answer empty. Put one or more record refs in AnswerRef, joined by ;. For repeatable fields, append the repeat index with ~:

{ "ref": "100912760", "answerRef": "100912758~1;100912759~2" }

Placeholders

Set UsePlaceholder: true on any answer to render it as a placeholder in the generated document rather than resolving it to the supplied value. Useful for review drafts where the final values aren't known yet.

{ "ref": "100912750", "answer": "", "usePlaceholder": true }