> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Form Field API | FusionAuth Docs

Learn about the APIs for creating, retrieving, updating and deleting form fields.

# Form Field API

[Edit on GitHub](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/docs/apis/custom-forms/form-fields.mdx)

[View Markdown](https://fusionauth.io/docs/apis/custom-forms/form-fields.md)

This feature is only available in paid plans. To learn more, see [our pricing page](https://fusionauth.io/pricing.md).

A FusionAuth Form Field is an object that can be customized to receive input within a FusionAuth [Form](https://fusionauth.io/docs/apis/custom-forms/forms.md).

The following APIs are provided to manage Forms Fields.

## Create a Form Field[#](#create-a-form-field)

This API is used to create a new Form Field.

### Request[#](#request)

Create a Form Field with a randomly generated Id

POST/api/form/field

OpenAPI Spec

Create a Form Field with the provided unique Id

POST/api/form/field/{fieldId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters)

`fieldId`UUIDoptionalDefaults 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[#](#request-body)

`field.confirm`BooleanoptionalDefaults 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`UUIDoptional

The Id of an existing [Consent](https://fusionauth.io/docs/apis/consents.md). 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`StringoptionalDefaults to text

The Form Field control. The possible values are:

*   `checkbox`
*   `number`
*   `password`
*   `radio`
*   `select`
*   `textarea`
*   `text`

The field control can only be set for custom fields, and if not provided the default value will be `text`. For all managed fields, such as `user.firstName`, the control will be set by FusionAuth and it may not be modified.

`field.data`Objectoptional

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:

```json
{
"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`Stringoptional

A description of the Form Field.

`field.key`Stringrequired

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.preferredLanguages` Available since 1.20.0
*   `registration.roles` Available since 1.20.0
*   `registration.timezone` Available since 1.20.0
*   `registration.username`
*   `user.birthDate`
*   `user.email`
*   `user.firstname`
*   `user.fullName`
*   `user.imageUrl` Available since 1.20.0
*   `user.lastName`
*   `user.middleName`
*   `user.mobilePhone`
*   `user.password`
*   `user.phoneNumber` Available since 1.59.0
*   `user.preferredLanguages` Available since 1.20.0
*   `user.timezone` Available since 1.20.0
*   `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.

```plaintext
user.data.favoriteColor=Favorite color
```

`field.name`Stringrequired

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.

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
red=Roja
green=Verde
blue=Azul
```

`field.required`BooleanoptionalDefaults to false

Determines if a value is required to complete the form.

`field.type`StringoptionalDefaults to 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. The value must be formatted as ISO-8601 or `YYY-MM-DD`, you may want to use a JavaScript data picker that can convert the selected value to this format.
*   `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

All user provided input will be validated to ensure it can be stored in this data type. If the user input cannot be converted a validation error will be shown to the user. When providing options for this control each option must also be compatible with this data type. When using the `consent` type, the field **consentId** is required and must be included in the request. The data type can only be set for custom fields, and if not provided the default value will be `string`. For all managed fields, such as `` user.firstName` ``, the data type will be set by FusionAuth and it may not be modified.

`field.validator.enabled`BooleanoptionalDefaults to false

Determines if user input should be validated.

`field.validator.expression`Stringoptional

A regular expression used to validate user input. Must be a valid regular expression pattern.

See [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) for examples and syntax.

*Example Request JSON*

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

### Response[#](#response)

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

*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](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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[#](#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](https://fusionauth.io/docs/apis/consents.md). 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`

`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:

```json
{
"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](https://fusionauth.io/docs/reference/data-types.md#instants) 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.preferredLanguages` Available since 1.20.0
*   `registration.roles` Available since 1.20.0
*   `registration.timezone` Available since 1.20.0
*   `registration.username`
*   `user.birthDate`
*   `user.email`
*   `user.firstname`
*   `user.fullName`
*   `user.imageUrl` Available since 1.20.0
*   `user.lastName`
*   `user.middleName`
*   `user.mobilePhone`
*   `user.password`
*   `user.phoneNumber` Available since 1.59.0
*   `user.preferredLanguages` Available since 1.20.0
*   `user.timezone` Available since 1.20.0
*   `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.

```plaintext
user.data.favoriteColor=Favorite color
```

`field.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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.

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
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. The value must be formatted as ISO-8601 or `YYY-MM-DD`, you may want to use a JavaScript data picker that can convert the selected value to this format.
*   `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

`field.validator.enabled`Boolean

Determines if user input should be validated.

`field.validator.expression`String

A regular expression used to validate user input. Must be a valid regular expression pattern.

See [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) for examples and syntax.

*Example Response JSON*

```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[#](#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[#](#request-1)

Retrieve all of the Form Fields

GET/api/form/field

Retrieve a Form Field by Id

GET/api/form/field/{fieldId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters-1)

`fieldId`UUIDrequired

The unique Id of the Form Field to retrieve.

### Response[#](#response-1)

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.

*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](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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[#](#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](https://fusionauth.io/docs/apis/consents.md). 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`

`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:

```json
{
"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](https://fusionauth.io/docs/reference/data-types.md#instants) 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.preferredLanguages` Available since 1.20.0
*   `registration.roles` Available since 1.20.0
*   `registration.timezone` Available since 1.20.0
*   `registration.username`
*   `user.birthDate`
*   `user.email`
*   `user.firstname`
*   `user.fullName`
*   `user.imageUrl` Available since 1.20.0
*   `user.lastName`
*   `user.middleName`
*   `user.mobilePhone`
*   `user.password`
*   `user.phoneNumber` Available since 1.59.0
*   `user.preferredLanguages` Available since 1.20.0
*   `user.timezone` Available since 1.20.0
*   `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.

```plaintext
user.data.favoriteColor=Favorite color
```

`field.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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.

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
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. The value must be formatted as ISO-8601 or `YYY-MM-DD`, you may want to use a JavaScript data picker that can convert the selected value to this format.
*   `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

`field.validator.enabled`Boolean

Determines if user input should be validated.

`field.validator.expression`String

A regular expression used to validate user input. Must be a valid regular expression pattern.

See [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) for examples and syntax.

*Example Response JSON*

```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[#](#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](https://fusionauth.io/docs/apis/consents.md). 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`

`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:

```json
{
"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].inseertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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.preferredLanguages` Available since 1.20.0
*   `registration.roles` Available since 1.20.0
*   `registration.timezone` Available since 1.20.0
*   `registration.username`
*   `user.birthDate`
*   `user.email`
*   `user.firstname`
*   `user.fullName`
*   `user.imageUrl` Available since 1.20.0
*   `user.lastName`
*   `user.middleName`
*   `user.mobilePhone`
*   `user.password`
*   `user.phoneNumber` Available since 1.59.0
*   `user.preferredLanguages` Available since 1.20.0
*   `user.timezone` Available since 1.20.0
*   `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.

```plaintext
user.data.favoriteColor=Favorite color
```

`fields[x].lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the form field was last updated in the FusionAuth database.

`fields[x].name`String

The unique name of the Form Field.

`fields[x].confirm`Array<String>

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

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
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. The value must be formatted as ISO-8601 or `YYY-MM-DD`, you may want to use a JavaScript data picker that can convert the selected value to this format.
*   `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

`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*

```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[#](#update-a-form-field)

This API is used to update an existing Form Field.

You must specify all of the properties of the Form Field when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing Form Field and your new data. It replaces the existing Form Field with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing Form Field.

Some attributes, such as **type**, cannot be changed after form field creation.

### Request[#](#request-2)

Update the Form Field with the given Id

PUT/api/form/field/{fieldId}

OpenAPI Spec

PATCH/api/form/field/{fieldId}

OpenAPI Spec

For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:

*   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
*   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`

For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method).

Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Parameters[#](#request-parameters-2)

`fieldId`UUIDrequired

The Id of the Form Field to update.

#### Request Body[#](#request-body)

`field.confirm`BooleanoptionalDefaults 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`UUIDoptional

The Id of an existing [Consent](https://fusionauth.io/docs/apis/consents.md). 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.data`Objectoptional

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:

```json
{
"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`Stringoptional

A description of the Form Field.

`field.name`Stringrequired

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.

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
red=Roja
green=Verde
blue=Azul
```

`field.required`BooleanoptionalDefaults to false

Determines if a value is required to complete the form.

`field.validator.enabled`BooleanoptionalDefaults to false

Determines if user input should be validated.

`field.validator.expression`Stringoptional

A regular expression used to validate user input. Must be a valid regular expression pattern.

See [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) for examples and syntax.

*Example Request JSON*

```json
{
  "field": {
    "data": {
      "leftAddOn": "send"
    },
    "description": "Updated information about this custom field",
    "name": "Custom, updated, first-name Form Field",
    "required": false
  }
}
```

### Response[#](#response-2)

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

*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](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 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](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you are trying to update 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[#](#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](https://fusionauth.io/docs/apis/consents.md). 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`

`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:

```json
{
"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](https://fusionauth.io/docs/reference/data-types.md#instants) 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.preferredLanguages` Available since 1.20.0
*   `registration.roles` Available since 1.20.0
*   `registration.timezone` Available since 1.20.0
*   `registration.username`
*   `user.birthDate`
*   `user.email`
*   `user.firstname`
*   `user.fullName`
*   `user.imageUrl` Available since 1.20.0
*   `user.lastName`
*   `user.middleName`
*   `user.mobilePhone`
*   `user.password`
*   `user.phoneNumber` Available since 1.59.0
*   `user.preferredLanguages` Available since 1.20.0
*   `user.timezone` Available since 1.20.0
*   `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.

```plaintext
user.data.favoriteColor=Favorite color
```

`field.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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.

The options for a field must conform to the **field.type**. If the **field.type** is `number`, the options must be numbers. If the **field.type** is `boolean`, only `true` and/or `false` are allowed.

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

```properties
red=Red
green=Green
blue=Blue
```

Spanish

```properties
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. The value must be formatted as ISO-8601 or `YYY-MM-DD`, you may want to use a JavaScript data picker that can convert the selected value to this format.
*   `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

`field.validator.enabled`Boolean

Determines if user input should be validated.

`field.validator.expression`String

A regular expression used to validate user input. Must be a valid regular expression pattern.

See [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) for examples and syntax.

*Example Response JSON*

```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[#](#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[#](#request-3)

Delete a Form Field by Id

DELETE/api/form/field/{fieldId}

OpenAPI Spec

#### Request Parameters[#](#request-parameters-3)

`fieldId`UUIDrequired

The unique Id of the Form Field to delete.

### Response[#](#response-3)

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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. |