Form Requirements Reference

When you call GET /v1/providers/{id}, the response includes a form_requirements array describing the fields that must be collected from the user before submitting a claim. This page is the complete reference for the field types, validators, and properties you may encounter in that array.

Field types

The type property on each field determines what kind of input to render. There are four field types:

Text fields (`string`)

The most common field type. Renders a text input with optional validation and formatting.

Properties:

Property	Type	Required	Description
`id`	string	Yes	The form field ID. Use this as the key in `user_form_fields` when submitting the claim.
`label`	string	Yes	Display name to show the user.
`type`	string	Yes	Always `"string"` for text fields.
`validator`	string	No	Validation rule to apply (see Validators). If empty, the field is not required.
`required`	boolean	No	Whether the field must be filled.
`max_length`	integer	No	Maximum number of characters allowed.
`hint`	string	No	Hint text to display on the form field before user input (e.g. `"Enter your name"`).
`error_message`	string	No	Message to display when validation fails.
`placeholder`	string	No	Placeholder text to prefill in the field (e.g. a known email address).
`max_lines`	integer	No	Maximum number of lines for multi-paragraph entry.
`keyboard_type`	string	No	Hint for the device keyboard. One of: `name`, `number`, `phone`, `streetAddress`, `datetime`, `multiline`.
`input_formatter`	string	No	Restricts input format (see Input formatters).
`auto_fill_hints`	string[]	No	Hints for browser/device autofill (e.g. `["given_name"]`, `["email"]`).
`compliance_label`	string	No	Alternate label some partners may prefer to display instead of `label`. For example, a provider might label a field `"Member ID or SSN"`, but a partner may prefer to show just `"Member ID"`.
`compliance_validator`	string	No	Alternate validator to use when `compliance_label` is active. For example, changing from `ssn` to `ssnLastFour` when the label changes from `"SSN"` to `"Last 4 Digits of SSN"`. Only applies when `compliance_label` is also set.

Example:

{
  "label": "SSN",
  "compliance_label": "Last 4 Digits of SSN",
  "id": "ssn",
  "type": "string",
  "validator": "ssn",
  "compliance_validator": "ssnLastFour",
  "required": true,
  "input_formatter": "digitsOnly"
}

Example with autofill hints:

{
  "label": "First Name",
  "id": "first_name",
  "type": "string",
  "validator": "raw",
  "required": true,
  "auto_fill_hints": ["given_name"]
}

Radio fields (`radio`)

Single-select from a list of options. Renders as radio buttons where only one option can be selected.

Properties:

Property	Type	Required	Description
`id`	string	Yes	The form field ID.
`label`	string	Yes	Label for the radio group.
`type`	string	Yes	Always `"radio"`.
`values`	RadioValue[]	Yes	List of selectable options (see below).
`required`	boolean	No	Whether a selection is required.
`is_required`	boolean	No	Alias for `required`. Defaults to `true`.
`error_text`	string	No	Error text when required but nothing selected.
`default_value`	RadioValue	No	The pre-selected option.

RadioValue object:

Property	Type	Description
`label`	string	The text displayed for this option.
`value`	string	The value submitted when this option is selected.

Example:

{
  "label": "Address Change?",
  "id": "address_change",
  "type": "radio",
  "values": [
    { "label": "Yes", "value": "Yes" },
    { "label": "No", "value": "No" }
  ],
  "required": true
}

Radio text fields (`radiotext`)

A hybrid control that presents multiple text inputs as radio options — only one can be selected at a time. Each option is a full text field (with the same properties as the string type above).

Properties:

Property	Type	Required	Description
`id`	string	Yes	The form field ID.
`label`	string	Yes	Label for the radio text group.
`type`	string	Yes	Always `"radiotext"`.
`values`	TextFieldDTO[]	Yes	List of text field definitions (same structure as `string` fields).
`is_required`	boolean	No	Whether a selection is required. Defaults to `true`.
`error_text`	string	No	Error text when required but nothing selected.
`default_value`	TextFieldDTO	No	The pre-selected text field option.

Date fields (`date`)

Renders a date picker.

Properties:

Property	Type	Required	Description
`id`	string	Yes	The form field ID.
`label`	string	Yes	Label for the date field.
`type`	string	Yes	Always `"date"`.
`validator`	string	No	Validation rule (typically `"raw"`).
`required`	boolean	No	Whether the field must be filled.
`hint`	string	No	Hint text to show while the field is focused but empty.
`error_message`	string	No	Message to display when validation fails.
`initial_date`	string	No	Optional initial date to pre-populate.
`auto_fill_hints`	string[]	No	Hints for browser/device autofill (e.g. `["birthday"]`).

Example:

{
  "label": "Date of Birth",
  "id": "date_of_birth",
  "type": "date",
  "validator": "raw",
  "required": true,
  "auto_fill_hints": ["birthday"]
}

Validators

The validator property specifies the validation rule and expected format for a field's value. Values that do not pass validation should be rejected before submission.

`raw`

No validation. Any string value is accepted, including empty.

`required`

The field must contain a non-empty value. No format constraints beyond that.

`email`

Must be a valid email address per RFC 5322.

Format: user@example.com

`phone`

Must be a 10-digit US phone number with no spaces, dashes, or other formatting.

Format: 5551234567

`number`

Must contain only digit characters (0-9).

Format: 123456

`ssn`

Must be exactly 9 digits with no dashes or spaces.

Format: 123456789

`ssnLastFour`

Must be exactly 4 digits.

Format: 1234

Additional validators may be added over time. If you encounter a validator not listed here, apply the validation described by its name.

Input formatters

The input_formatter property specifies how input should be restricted in a string field. Formatters should be applied at input time to prevent invalid characters.

`digitsOnly`

Only digit characters (0-9) should be accepted. Non-digit input should be rejected or stripped.

`ssn`

Input should be restricted to digits. Submit as 9 raw digits without dashes (e.g. 123456789). If you display the value to the user with dashes (###-##-####), strip them before submission.

Submitted value formats

When building the user_form_fields object for claim submission, use the following formats for each field type:

Field Type	Submitted Value	Example
`string`	The raw text value. If an `ssn` input formatter is used, submit raw digits without dashes.	`"Jane"`, `"123456789"`
`radio`	The `value` property of the selected `RadioValue` object (not the `label`).	`"Yes"`, `"Male"`
`radiotext`	The text input value from the selected option.	`"custom text"`
`date`	ISO 8601 UTC datetime string.	`"2026-04-08T00:00:00.000Z"`

Full provider example

Below is a complete form_requirements response from a real provider, showing several field types and validators together:

{
  "id": "901392c2-1d41-40f8-abcb-1995e4a7e297",
  "name": "Navia",
  "logo": "https://ocvtbxkudfyeyziuewun.supabase.co/storage/v1/object/public/assets/providers/901392c2-1d41-40f8-abcb-1995e4a7e297/navia-logo.png",
  "type": "FSA",
  "form_requirements": [
    {
      "label": "First Name",
      "id": "first_name",
      "type": "string",
      "validator": "raw",
      "required": true,
      "auto_fill_hints": ["given_name"]
    },
    {
      "label": "Last Name",
      "id": "last_name",
      "type": "string",
      "validator": "raw",
      "required": true,
      "auto_fill_hints": ["family_name"]
    },
    {
      "label": "SSN or Employee ID",
      "compliance_label": "Employee ID",
      "id": "ssn_or_id",
      "type": "string",
      "validator": "number",
      "required": true
    },
    {
      "label": "Street Address",
      "id": "street",
      "type": "string",
      "validator": "raw",
      "required": true,
      "auto_fill_hints": ["street_address_line1"]
    },
    {
      "label": "City",
      "id": "city",
      "type": "string",
      "validator": "raw",
      "required": true,
      "auto_fill_hints": ["address_level2"]
    },
    {
      "label": "State",
      "id": "state",
      "type": "string",
      "validator": "raw",
      "required": true,
      "auto_fill_hints": ["address_level1"]
    },
    {
      "label": "Zip Code",
      "id": "zip_code",
      "type": "string",
      "validator": "number",
      "required": true,
      "auto_fill_hints": ["postal_code"]
    },
    {
      "label": "Telephone Number",
      "id": "telephone_number",
      "type": "string",
      "validator": "phone",
      "required": true,
      "auto_fill_hints": ["telephone_number_national"]
    },
    {
      "label": "Employer Name",
      "id": "employer_name",
      "type": "string",
      "validator": "raw",
      "required": true
    },
    {
      "label": "Email Address",
      "id": "email_address",
      "type": "string",
      "validator": "email",
      "required": true,
      "auto_fill_hints": ["email"]
    }
  ]
}

Field types​

Text fields (string)​

Radio fields (radio)​

Radio text fields (radiotext)​

Date fields (date)​

Validators​

raw​

required​

email​

phone​

number​

ssn​

ssnLastFour​

Input formatters​

digitsOnly​

ssn​

Submitted value formats​

Full provider example​

Field types

Text fields (`string`)

Radio fields (`radio`)

Radio text fields (`radiotext`)

Date fields (`date`)

Validators

`raw`

`required`

`email`

`phone`

`number`

`ssn`

`ssnLastFour`

Input formatters

`digitsOnly`

`ssn`

Submitted value formats

Full provider example