Configuration API: Adding and Updating Fields

Fields are another name for the controls -- checkboxes, radio buttons, text boxes, etc. -- that can be used on your login and registration forms. You can view, add, modify, or delete fields by using the following Configuration API endpoints:

In this article you'll find information about:

  • Common field attributes. Attributes that are are supported by all field types.
  • Type-specific field attributes. Attributes that might be supported on fields A, B, and C, but not on fields D and E.
  • Validations. Used to verify the values in a field before a form is submitted. For example, you might verify that a field that contains the user's zipcode has a maximum of 5 characters and that it contains only numbers.

You'll also find detailed examples that demonstrate how to add each field type to a form.

   
Common Field Attributes

All fields share a set of common attributes. These common field attributes include the following:

Attribute Required Description

type

Yes

The type of field that you wish to create or update. Currently supported field types are:

Click on one of the types for a full example of a field definition.

name

Yes

A unique name used to identify the field (cannot contain spaces). For example:

"name": "myCoolField"

schemaAttribute

Yes

A path to the schema attribute in the profile record to which this field's value should be mapped. For example:

"schemaAttribute": "primaryAddress.phone"

label

No

An optional field label used by the JavaScript SDK. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers. For example:

"label": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

tip

No

An optional field tooltip that is used by the JavaScript SDK. It is not necessary for pure API implementations. It must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers. For example:

"tip": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

validation

No

An optional list of validations that should be applied to this field. Validations have the following attributes:

  • rule (required)

The name of the validation rule to apply. Must be one of the validations allowed for this field's type. 

  • value (required)

The value to use for validation. For some validations this will just be true or false (for example, required). For others this will be a configuration value for the validation. 

  • message (required)

The error message to be used if the validation fails. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers. Message is not supported by the matchOptions validation, but is required for all others.

For example:

"validation": [
  {
    "rule": "required",
    "value": "true",
    "message": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    }
  }
]

   

Type-specific Field Attributes

Each type of field has additional parameters specific to it. Refer to the table at the end of this section to see which attributes apply to which fields.

Attribute Required Description

socialProfileData

No

When a user logs in using a social provider, the Identity Cloud Social Login service returns the social provider in the form of a Portable Contact payload. You can use the socialProfileData attribute to specify which data from the social profile should be used to populate the value for this field in the user record. For example:

"socialProfileData": "profile.name.familyName"

placeholder

No

This is used as the placeholder attribute on form elements when using the JavaScript SDK. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers. For example:

"placeholder": {
  "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
}

preChecked

No

This only applies to the checkbox field type. If set to true, the checkbox will appear pre-checked to new users registering with the JavaScript SDK. This is useful if you want to require that users specifically opt out of something (for example, a newsletter). For example:

"preChecked":true

submitValue

No

This only applies to the checkbox field type. Use this if you need to specify the submit value of a check box (that is, the check box should submit a value other than "on").

"submitValue": "true"

options

Yes

For the radio and select fields, you must define the options to be displayed. Options have the following attributes:

  • disabled (optional)

Set this to true to disable the option.

  • label (optional)

The label to display for this option. This must be a reference to a translation identifier. Make a call to /config/{app}/flows/{flow}/locales/{locale} for a list of valid identifiers.

  • selected (optional)

Set this to true to select this option by default. Only one option in a field can have this attribute.

  • value (optional)

The value of this option.

For example:

"options": [
  {
    "selected": true,
    "label": {
      "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
    },
    "value": "waffles"
  }
]

The fields that each type-specific attribute applies to are shown in the following table.

Attribute

text

email

password

checkbox

radio

select

textarea

socialProfileData

yes

yes

-

-

-

-

yes

placeholder

yes

yes

yes

-

-

-

yes

preChecked

-

-

-

yes

-

-

-

submitValue

-

-

-

yes

-

-

-

options

-

-

-

-

yes

yes

-

   

Validations

Each field supports a subset of the validations available. Refer to the table at the end of this section to determine which validations are available to you.

Attribute Description

blacklist

Takes a list of disallowed strings as its value. For example:

{
  "rule": "blacklist",
  "value": "blacklisted_words",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

format

Asserts that the field conforms to a certain format. It takes one of the following predefined formats as its value:

  • alpha - Only allows alphabetic characters, and must contain at least one character. Defined as /^[a-z]+$/i.
  • alphaExtended - Only allows alphabetic characters, dashes (-), and single quotes('). The field value must contain at least one character. Defined as /^[a-zA-Z\-']+$/.
  • alphaExtendedSpaces - Only allows alphabetic characters, dashes (-), single quotes('), and whitespace characters (\r, \n, \t, and \f). Defined as /^[a-zA-Z\-'\s]+$/.
  • alphaNumeric - Only allows alphabetic and numeric characters. The field value must contain at least one character. Defined as /^[a-z0-9]+$/i.
  • alphaNumericExtended - Only allows alphabetic and numeric characters. Allows for dashes (-), underscores (_), and periods (.) within the value, so long as they are not at the beginning or the end. The field value must contain at least three characters. Defined as /^[a-z][-a-z0-9\s_.]*[a-z0-9]$/i.
  • email - Only allows valid email addresses. Defined as /^.+@(?:[^.]+\.)+(?:[^.]{2,})$/.
  • i18nAlphaNumeric - Allows only alphanumeric characters without excluding characters containing accents (for example, é). Defined as /^[^-\s^`~!@#$%^&*()_=+\[{\]}\|;:‘“,<.>/?]+$/, it disallows the following characters:
    • whitespace characters (\r, \n, \t, and \f)
    • dashes (-)
    • carets (^)
    • backticks (`)
    • exclamation points (!)
    • at signs (@)
    • number signs (#)
    • dollar signs ($)
    • percent signs (%)
    • ampersands (&)
    • asterisks (*)
    • parentheses (())
    • underscores (_)
    • equal signs (=)
    • plus signs (+)
    • square brackets ([])
    • curly braces ({})
    • pipes (|)
    • semicolons (;)
    • colons (:)
    • single quotes (')
    • double quotes (")
    • commas (,)
    • angle brackets (<>)
    • periods (.)
    • forward slashes (/)
    • question marks (?)

​For example:

{
  "rule": "format",
  "value": "email",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

noWhitespace

Disallows whitespace characters (\r, \n, \t, and \f). Defined as /^\S*$/.

numeric

Only allows numeric characters. Defined as /^(\d+)$/.

numericReal

Only allows real number values. Defined as /^(\d+\.?\d*|\.\d+|\-\d+\.?\d*|\-\.\d+)$/, it allows numbers in the following formats:

  • 1234
  • 12.34
  • .1234
  • -1234
  • -12.34
  • -.1234

phone

Only allows valid phone numbers. Defined as /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/, it allows phone numbers in the following formats:

  • (123)-456-7890
  • (123).456.7890
  • (123) 456 7890
  • 123-456-7890
  • 123.456.7890
  • 123 456 7890
     

phoneInternational

Similar to the phone validation, but allows for an optional one to four preceding numbers. Defined as /^(\d{1,4}[-. ]?)?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/.

zipCode

Only allows five character numeric values. Defined as /^\d{5}$/.

zipCode+4

Similar to the zipCode validation, but allows for an optional plus-four code. Defined as /^\d{5}(\-\d{4})?$/.

match

Asserts that a field value matches the value of another field. Its value must be set to another existing field. For example:

{
  "rule": "match",
  "value": "confirmPasswordField",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

matchOptions

Protects against invalid input on select fields by enforcing that the value submitted be one of the options defined in the field. Set this to false only if you plan on dynamically populating the select options yourself. This is added to select fields by default. For example:

{
  "rule": "matchOptions",
  "value": True
}

maxLength

Asserts that the value of a field is at most the length set as the value of this validation. For example:

{
  "rule": "maxLength",
  "value": 30,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

minLength

Asserts that the value of a field is at least the length set as the value of this validation. For example:

{
  "rule": "minLength",
  "value": 4,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

minYears

Asserts that the value from a dateselect field is at least so many years in the past. For example:

{
  "rule": "minYears",
  "value": 18,
  "message": {
    "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
  }
}

required

Asserts that a value is provided for this field. Set to true to enable this validation. For example:

{
  "rule": "required",
  "value": true,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

unique

Asserts that the value of this field is unique when compared to all records within the Identity Cloud application. Set to true to enable this validation. For example:

{
  "rule": "unique",
  "value": true,
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }

}

whitelist

Takes a list of allowed strings as its value. All other strings are disallowed. For example:

{
  "rule": "whitelist",
  "value": ["only allow this","or_this_one!"],
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

clientFunctionName

Name of the function to use for validation on the client. For example:

{
  "rule": "clientFunctionName",
  "value": "functionName",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

serverRegexSetting

Server Setting of regex to use for validation. For example:

{
  "rule": "serverRegexSetting",
  "value": "serverRegexSetting",
  "message": {
    "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
  }
}

The validations and the fields they apply to are shown in the following table:

checkbox

dateselect

email

password

radio

select

text

textarea

blacklist

-

-

-

-

-

-

yes

-

format

-

-

yes*

yes

-

-

yes

yes

match

-

-

yes

yes

yes

yes

yes

-

matchOptions

-

-

-

-

-

yes

-

-

maxLength

-

-

yes

yes

-

-

yes

yes

minLength

-

-

yes

yes

-

-

yes

yes

minYears

-

yes

-

-

-

-

-

-

required

yes

yes

yes

yes

yes

yes

yes

yes

unique

-

-

yes

-

-

-

yes

-

whitelist

-

-

-

-

-

-

yes

-

clientFunctionName

-

yes

yes

yes

-

yes

yes

yes

serverRegexSetting

-

yes

yes

yes

-

yes

yes

yes

Fields of type email check for correctly-formatted emails by default. This cannot be overridden.

Full Examples

Full examples showing how to add different field types to a form.

Full Example: checkbox
 


{
  "type": "checkbox",
  "name": "myCustomCheckboxField",
  "schemaAttribute": "optIn.status",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "preChecked": true,
  "submitValue": "yes",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

   

Full Example: dateselect
 


{
  "name": "birthdate",
  "schemaAttribute": "birthday",
  "type": "dateselect",
  "label": {
    "key": "8122c314a4e9d558f6d3eedfb2446376"
  },
  "yearLabel": {
    "key": "acb8b9cedb63cb5930bae0fb1c2d50cc"
  },
  "monthLabel": {
    "key": "ace9326798de56c595568a7a4141972c"
  },
  "dayLabel": {
    "key": "6f44a1db770c928b0d40bb980548f43d"
  },
  "monthNames": [
    {
      "key": "66fcba24722d94d03167df4d29a3fcde"
    },{
      "key": "eec9c536de325f7f66669a7a61a55fc0"
    },{
      "key": "b8a35f47cfde6c15643c74804f9a6421"
    },{
      "key": "399c58387be99853b53ffc4f778814ab"
    },{
      "key": "ab66d779cf23720afbc4f2c49a296728"
    },{
      "key": "9089a6c3cc7b9d447c5aa870a38a49bf"
    },{
      "key": "24ea0188feb2be9c0a6fc0fffa329009"
    },{
      "key": "f814c7e7884980bfbe637bc8b7d5a798"
    },{
      "key": "cbbd277bc1b7f3034d4b8a5fc7c0a717"
    },{
      "key": "17ef13bbd9bd987fc16b4a26665e99ce"
    },{
      "key": "dd1b34fbac69ea3440260d0b25f660ea"
    },{
      "key": "368ace206c6cd848a8eb028fcf44a895"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "minYears",
      "value": 18,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

   

Full Example: email
 


{
  "type": "email",
  "name": "myCustomEmailField",
  "schemaAttribute": "email",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.email",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

   

Full Example: password
 


{
  "type": "password",
  "name": "myCustomPasswordField",
  "schemaAttribute": "password",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "minLength",
      "value": 16,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "match",
      "value": "myCustomPasswordConfirmField",
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

   

Full Example: radio
 


{
  "type": "radio",
  "name": "myCustomRadioField",
  "schemaAttribute": "favorites.breakfastFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "key": "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "waffles"
    },
    {
      "label": {
        "key": "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "pancakes"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

   

Full Example: select
 


{
  "type": "select",
  "name": "myCustomSelectField",
  "schemaAttribute": "favorites.lunchFood",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "options": [
    {
      "selected": true,
      "label": {
        "8a8508aa-f939-472b-bad2-59f6c0089a60"
      },
      "value": "hotdogs"
    },
    {
      "label": {
        "c8050744-9b1d-4360-89e7-b37802d59c4a"
      },
      "value": "hamburgers"
    }
  ],
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}

   

Full Example: text
 


{
  "type": "text",
  "name": "myCustomTextField",
  "schemaAttribute": "displayName",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.displayName",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "required",
      "value": true,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    },{
      "rule": "unique",
      "value": true,
      "message": {
        "key": "63f7c18f-521a-4b4f-94c4-0b04b870c82e"
      }
    }
  ]
}

   

Full Example: textarea
 


{
  "type": "textarea",
  "name": "myCustomTextareaField",
  "schemaAttribute": "profileBlurb",
  "label": {
    "key": "b6ced670-7140-4446-9839-da3474860b1a"
  },
  "tip": {
    "key": "8b93448a-6f00-448c-952b-0f1536107cf7"
  },
  "socialProfileData": "profile.aboutMe",
  "placeholder": "6e15067b-2ca5-43c3-af96-930766d63375",
  "validation": [
    {
      "rule": "maxLength",
      "value": 500,
      "message": {
        "key": "bb2b21a1-98df-4dce-84f7-534013c46225"
      }
    }
  ]
}