For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help CenterOpenAPI SpecStatus
OverviewInquiriesTransactionsRelaysAPI ReferenceChangelog
OverviewInquiriesTransactionsRelaysAPI ReferenceChangelog
  • Overview
    • Inquiries Overview
    • Inquiry Model Lifecycle
    • Inquiry Templates
  • Managing inquiries
    • Creating Inquiries
    • Resuming Inquiries
    • Accessing Inquiry status and data
      • Inquiry Fields
      • Inquiry Sessions
      • Inquiry One-Time Links (OTLs)
      • Reference IDs
      • Inquiry Expiration
      • Inquiry Theming
      • Inquiry Signals
      • Browser & Device Support
      • Internationalization
      • Accessibility
  • Hosted Flow integration
  • Embedded Flow integration
  • Mobile SDK integration
    • Overview
    • Webview
  • Troubleshooting
    • Troubleshooting Steps
    • Troubleshooting Common Issues
LogoLogo
Help CenterOpenAPI SpecStatus
On this page
  • Field values and customers
  • Field types
  • Prefilling Inquiry fields
  • How to do it
  • Reading fields via API
  • Writing fields via API
  • Field schema policies
  • Experimental
Managing inquiriesReference guides

Inquiry Fields

Was this page helpful?
Previous

Inquiry Sessions

Next
Built with

Inquiries store values collected from the customer in fields, and inquiry template versions define the field schemas.

You can configure custom fields on your template field schema to support your use cases. Please contact support or your CSM to get started.

Field values and customers

Fields are expressly intended for storing customer-supplied information and are meant to be readable and writable by the end user. We do not recommend storing data that should not be exposed to end users in Inquiry Fields.

Field types

NameInput FormatNotes
array['a', 'b', 'c'], [1, 2, 3]Typed array
booleantrue, false
choices'enum_1'
date'YYYY-MM-DD'ISO 8601 string
datetime'YYYY-MM-DDThh:mm:ss.000Z'ISO 8601 string
file{ filename: string; io: base64 data; }Serializes as:{ filename: string; byte_size: integer; mime_type: string; url: string; }
hashDependent on configurationDictionary with string keys and field values
multi_choices['enum_1', 'enum_2']Array of strings
number123, 123.45
string'hello world'

Prefilling Inquiry fields

If you already have information you’ve collected on your user, you can pre-populate their inquiry with this information at creation time. This will:

  • Streamline the user experience. If the user has already given you this information, there’s no need to have them type it again into Persona. You can prefill the inquiry and just have the user confirm everything is correct.
  • Have an extra level of assurance that the user’s information is valid. For example, if you pass through a name and birthdate, you can configure your template to check that the information extracted from the user’s Government ID matches what was prefilled.

How to do it

  • Server API: (recommended) Pass in the desired fields upon creation of the inquiry via API call. This is Persona’s recommended method.
  • SDK: When implementing with one of Persona’s SDKs and creating the inquiry on-the-fly, you can send the fields over in the builder.
  • Hosted: You can add fields to the URL when using a generic inquiry template link.

Reading fields via API

An inquiry’s fields can be retrieved via the external API using a GET request. Fields are also passed back to the caller in inquiry flows on completion.

Fields are serialized as a nested map of field name to field type and field value. For example:

json
1{
2  "name-first": {
3    "type": "string",
4    "value": "John",
5  },
6  "name-last": {
7    "type": "string",
8    "value": "Doe",
9  },
10  "birthdate": {
11    "type": "date",
12    "value": "1980-12-25",
13  }
14}

Writing fields via API

When updating an inquiry via API, fields should be passed as a map of field name to field value. Field type does not need to be specified.

json
1{
2  "name-first": "John",
3  "name-last": "Doe",
4  "birthdate": "1980-12-25"
5}

Field schema policies

Experimental

Field policies are currently in beta and are not generally available. If you think field policies fit your use case, please contact support or your CSM for more information.

Field behavior can be modified with field policies.

Field write policiesDescription
noneDefault. No special behavior.
write_onceThe field will become immutable after it has been set for the first time (via the end user, query string parameters, or external API). Setting a default value on the field schema will NOT cause the field to become immutable. Setting the field value to be null WILL cause the field to become immutable.
Field redaction policiesDescription
noneDefault. No special behavior.
neverThis field will never be redacted. This is intended to be used for fields such as timestamps or tracking terms of service acceptance, and is NOT intended to be used for fields containing PII.