Controlling Returned Data (Form Result API)

Helpdocs Admin Updated by Helpdocs Admin

Background: how Tokity forms work

Tokity's dynamic forms work similarly to Microsoft Forms or Google Forms. A form's definition is a JSON payload made up of fields, where each field includes:

  • A field type
  • A field name (the question)
  • A field description (Markdown)
  • Conditions controlling when the field should be displayed — for example, a field might only appear if a previous choice-based question was answered a certain way.

Because fields can depend on each other, a submitted form result isn't necessarily a simple flat list of "every field with its answer" — some fields may have been filled in, then later hidden because an earlier answer changed. The form-result Prefer option controls how the API handles this.

The Prefer header options

Directive

Values

Default

Purpose

content-type

markdown | html

markdown

Controls the format of each field's description.

form-result

default | can_display_only | has_answer_only

default

Controls which fields are included in a form result response.

content-type

Determines whether each field's description is returned as Markdown or pre-rendered HTML. This uses the same values as the content-type option on the Ticket and Workspace APIs, but here it applies specifically to field descriptions rather than ticket notes or workspace notes.

form-result

default Returns every field exactly as it was at the time of submission — including the form's structure and conditions as they existed then. If the form definition has since changed, that's not reflected here; the result is a snapshot of the submission.

Because conditions are frozen at submission time, it's possible for a field to have a recorded answer even though, by the current condition logic, it shouldn't be visible. This can happen when a contact fills in a field, then later changes an earlier answer that the field depends on — the dependent field becomes hidden going forward, but its previously submitted answer is still stored. With default, your UI or logic needs to resolve this yourself by evaluating the submitted result against its conditions.

can_display_only Resolves this for you: it only returns fields that would actually be visible, once all conditions have been evaluated against the submitted answers. Any field that ended up hidden by a later answer change is excluded — you don't need to re-evaluate conditions yourself.

has_answer_only Goes a step further than can_display_only — in addition to only including displayable fields, it also drops any optional field that has no answer. This gives you the minimal representation of what the contact actually submitted, excluding both hidden fields and empty optional ones.

Choosing the right option

  • Use default if you need the full historical record of a submission, including fields that are no longer valid under current conditions — useful for auditing or reconstructing exactly what happened at submission time.
  • Use can_display_only if you want the form result as it should be shown today, without hidden/stale fields, but still want to see optional fields even if left blank.
  • Use has_answer_only if you only care about what the contact actually filled in — the leanest, most minimal view of the result.

How did we do?

Controlling Returned Data (Ticket API)

Controlling Returned Data (Workspace API)

Contact