Form Field APIs

Overview

A FusionAuth Form Field is an object that can be customized to receive input within a FusionAuth Form.

The following APIs are provided to manage Forms Fields.

Create a Form Field

This API is used to create a new Form Field.

Request

Create a Form Field with a randomly generated Id

URI

POST /api/form/field

Create a Form Field with the provided unique Id

URI

POST /api/form/field/{fieldId}

Request Parameters

fieldId [UUID] Optional defaults to secure random UUID

The Id to use for the new Form Field. If not specified a secure random UUID will be generated.

Request Body

field.confirm [Boolean] Optional defaults to false

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

field.consentId [UUID] Optional

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

field.control [String] Optional See description for default information

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

field.data [Object] Optional

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

field.description [String] Optional

A description of the Form Field.

field.key [String] Required

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
field.name [String] Required

The unique name of the Form Field.

field.options [Array<String>] Optional

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
field.required [Boolean] Optional defaults to false

Determines if a value is required to complete the form.

field.type [String] Optional defaults to string with exceptions, see description

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

field.validator.enabled [Boolean] Optional defaults to false

Determines if user input should be validated.

field.validator.expression [String] Optional

A regular expression used to validate user input.

Example Request JSON
{
  "field": {
    "data": {
      "leftAddOn": "send"
    },
    "description": "Information about this custom field",
    "key": "user.firstName",
    "name": "Custom first-name Form Field",
    "required": true
  }
}

Response

The response for this API contains the Form Field that was created.

Table 1. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

field.confirm [Boolean]

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

field.consentId [UUID]

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

field.control [String]

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

field.data [Object]

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

field.description [String]

A description of the Form Field.

field.id [UUID]

The unique Id of the form field.

field.insertInstant [Long]

The instant that the form field was added to the FusionAuth database.

field.key [String]

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
field.lastUpdateInstant [Long]

The instant that the form field was last updated in the FusionAuth database.

field.name [String]

The unique name of the Form Field.

field.options [Array<String>]

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
field.required [Boolean]

Determines if a value is required to complete the form.

field.type [String]

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

field.validator.enabled [Boolean]

Determines if user input should be validated.

field.validator.expression [String]

A regular expression used to validate user input.

Example Response JSON
{
  "field": {
    "confirm": false,
    "control": "text",
    "data": {
      "leftAddOn": "send"
    },
    "description": "Information about this custom field",
    "id": "e96f02db-4567-43a6-a876-74a3869fe94a",
    "insertInstant": 1562189072183,
    "key": "user.firstName",
    "lastUpdateInstant": 1562189927638,
    "name": "Custom first-name Form Field",
    "required": true,
    "type": "string",
    "validator": {
      "enabled": false
    }
  }
}

Retrieve a Form Field

This API is used to retrieve a single Form Field by unique Id or all of the configured Form Fields.

Request

Retrieve all of the Form Fields

URI

GET /api/form/field

Retrieve a Form Field by Id

URI

GET /api/form/field/{fieldId}

Request Parameters

fieldId [UUID] Required

The unique Id of the Form Field to retrieve.

Response

The response for this API contains either a single Form Field or all of the Form Fields. When you call this API with an Id, the response will contain a single Form Field. When you call this API without an Id, the response will contain all of the Form Fields. Both response types are defined below along with an example JSON response.

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

field.confirm [Boolean]

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

field.consentId [UUID]

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

field.control [String]

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

field.data [Object]

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

field.description [String]

A description of the Form Field.

field.id [UUID]

The unique Id of the form field.

field.insertInstant [Long]

The instant that the form field was added to the FusionAuth database.

field.key [String]

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
field.lastUpdateInstant [Long]

The instant that the form field was last updated in the FusionAuth database.

field.name [String]

The unique name of the Form Field.

field.options [Array<String>]

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
field.required [Boolean]

Determines if a value is required to complete the form.

field.type [String]

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

field.validator.enabled [Boolean]

Determines if user input should be validated.

field.validator.expression [String]

A regular expression used to validate user input.

Example Response JSON
{
  "field": {
    "confirm": false,
    "control": "text",
    "data": {
      "leftAddOn": "send"
    },
    "description": "Information about this custom field",
    "id": "e96f02db-4567-43a6-a876-74a3869fe94a",
    "insertInstant": 1562189072183,
    "key": "user.firstName",
    "lastUpdateInstant": 1562189927638,
    "name": "Custom first-name Form Field",
    "required": true,
    "type": "string",
    "validator": {
      "enabled": false
    }
  }
}

Response Body

fields [Array]

The list of Form Field objects.

fields[x].confirm [Boolean]

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

fields[x].consentId [UUID]

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

fields[x].control [String]

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

fields[x].data [Object]

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

fields[x].description [String]

A description of the Form Field.

fields[x].id [UUID]

The unique Id of the form field.

fields[x].insertInstant [Long]

The instant that the Form Field was added to the FusionAuth database.

fields[x].key [String]

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
fields[x].lastUpdateInstant [Long]

The instant that the form field was last updated in the FusionAuth database.

fields[x].name [String]

The unique name of the Form Field.

fields[x].options [Array<String>]

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
fields[x].required [Boolean]

Determines if a value is required to complete the form.

fields[x].type [String]

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

fields[x].validator.enabled [Boolean]

Determines if user input should be validated.

fields[x].validator.expression [String]

A regular expression used to validate user input.

Example Response JSON
{
  "fields": [
    {
      "confirm": false,
      "control": "text",
      "data": {
        "leftAddOn": "send"
      },
      "description": "Information about this custom field",
      "id": "e96f02db-4567-43a6-a876-74a3869fe94a",
      "insertInstant": 1562189072183,
      "key": "user.firstName",
      "lastUpdateInstant": 1562189927638,
      "name": "Custom first-name Form Field",
      "required": true,
      "type": "string",
      "validator": {
        "enabled": false
      }
    }
  ]
}

Update a Form Field

This API is used to update an existing Form Field.

Request

Update the Form Field with the given Id

URI

PUT /api/form/field/{fieldId}

PATCH /api/form/field/{fieldId}

Available since 1.12.0

When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

 

Request Parameters

fieldId [UUID] Required

The Id of the Form Field to update.

Request Body

field.confirm [Boolean] Optional defaults to false

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

field.consentId [UUID] Optional

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

field.control [String] Optional See description for default information

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

field.data [Object] Optional

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

field.description [String] Optional

A description of the Form Field.

field.key [String] Required

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
field.name [String] Required

The unique name of the Form Field.

field.options [Array<String>] Optional

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
field.required [Boolean] Optional defaults to false

Determines if a value is required to complete the form.

field.type [String] Optional defaults to string with exceptions, see description

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

field.validator.enabled [Boolean] Optional defaults to false

Determines if user input should be validated.

field.validator.expression [String] Optional

A regular expression used to validate user input.

Example Request JSON
{
  "field": {
    "data": {
      "leftAddOn": "send"
    },
    "description": "Information about this custom field",
    "key": "user.firstName",
    "name": "Custom first-name Form Field",
    "required": true
  }
}

Response

The response for this API contains the Form Field that was updated.

Table 3. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to updated doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

field.confirm [Boolean]

Determines if the user input should be confirmed by requiring the value to be entered twice. If true, a confirmation field is included.

field.consentId [UUID]

The Id of an existing Consent. This field will be required when the type is set to consent.

Using a form field for consent allows you to leverage a FusionAuth consent to allow your end users to self consent to terms and service, end user license agreements, or other opt-in, or opt-out agreements during registration.

field.control [String]

The Form Field control. The possible values are:

  • checkbox

  • number

  • password

  • radio

  • select

  • textarea

  • text

When a predefined key field is used, control will be defaulted. The key value of
user.password defaults to password. All other key values default to text.

field.data [Object]

An object that can hold any information about the Form Field that should be persisted.

This may be useful to add additional meta data to the field that will help you style or render the Form Field. For example, in the JSON example an attribute is added to this data field as follows: 

{
  "data": {
    "leftAddOn": "user"
  }
}

This additional meta data is then used to render an icon on the Form Field. Use of this additional data is optional and not required to render the field.

field.description [String]

A description of the Form Field.

field.id [UUID]

The unique Id of the form field.

field.insertInstant [Long]

The instant that the form field was added to the FusionAuth database.

field.key [String]

The key is the path to the value in the user or registration object.

 

Predefined keys

Predefined keys are typed values managed by FusionAuth. When using a pre-defined key, the field data type and form control are not configurable.

  • registration.username

  • user.birthDate

  • user.email

  • user.firstname

  • user.fullName

  • user.lastName

  • user.middleName

  • user.mobilePhone

  • user.password

  • user.username

 

Custom Keys

When defining a key to store custom data, you may use one of the following prefixes:

  • user.data.

  • registration.data.

For example, in order to store a custom value on the user object to collect the User’s favorite color, set the key value equal to user.data.favoriteColor.

A valid key name must not contain spaces or special characters. An array may be specified by using the array syntax of [0] to indicate the first position in an array. Nested objects may be specified by using the object syntax of ['foo'] to indicate the named property of the object named foo. Consider the following examples:

  • user.data.preferences[0] would store the value in the first position of an array named preferences.

  • user.data.preferences['color'] would store the value in an object named preferences with a key of color.

 

Localization

You may localize the displayed value of this key during registration by adding the key to your theme. For example, if you specify the key value of user.data.favoriteColor this key value be rendered in the UI.

If you were to add the following messages to your theme, the localized form of the value will be shown to the end user. This allows you to provide a human readable field name and optionally localize the field name as well. 

user.data.favoriteColor=Favorite color
field.lastUpdateInstant [Long]

The instant that the form field was last updated in the FusionAuth database.

field.name [String]

The unique name of the Form Field.

field.options [Array<String>]

A list of options that are applied to checkbox, radio, or select controls.

You may localize the displayed values during registration by adding these values to your theme.

For example, if you specify the values ["red", "green", "blue"] as the field options, these will be stored on the user in this lowercase form. By default the values red, green and blue will be rendered in the UI.

If you were to add the following messages to your theme, the capitalized form of the values will be shown to the end user. This allows you to provide a human readable form of the value and optionally localize the displayed values.

Default
red=Red
green=Green
blue=Blue
Spanish
red=Roja
green=Verde
blue=Azul
field.required [Boolean]

Determines if a value is required to complete the form.

field.type [String]

The data type used to store the value in FusionAuth. The possible values are:

  • bool the value must be a boolean value, true or false

  • consent the value will be used to complete self consent

  • date the value will be stored as a date

  • email the value will be expected to be a valid email address

  • number the value will be stored as a numerical value

  • string the value will be stored as a string

If the value provided by the user cannot be converted to the requested data type a validation error will occur.

When using the date type, the only supported data format is ISO-8601 or YYY-MM-DD. You may want to use a JavaScript data picker that can convert the selected value to this format.

When using the consent type, the field consentId must be included in the request.

Defaults to string, unless user.birthDate, then date, or if user.email then email.

field.validator.enabled [Boolean]

Determines if user input should be validated.

field.validator.expression [String]

A regular expression used to validate user input.

Example Response JSON
{
  "field": {
    "confirm": false,
    "control": "text",
    "data": {
      "leftAddOn": "send"
    },
    "description": "Information about this custom field",
    "id": "e96f02db-4567-43a6-a876-74a3869fe94a",
    "insertInstant": 1562189072183,
    "key": "user.firstName",
    "lastUpdateInstant": 1562189927638,
    "name": "Custom first-name Form Field",
    "required": true,
    "type": "string",
    "validator": {
      "enabled": false
    }
  }
}

Delete a Form Field

This API is used to permanently delete a Form Field. A form field cannot be deleted when in use by a one or more forms.

Request

Delete a Form Field by Id

URI

DELETE /api/form/field/{fieldId}

Request Parameters

fieldId [UUID] Required

The unique Id of the Form Field to delete.

Response

This API does not return a JSON response body.

Table 4. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.