/config/{app}/flows/{flow}/forms

name

string

Yes

Name of the new form. It’s recommended that form names be limited to letters (uppercase and/or lowercase), numbers, and the underscore character (_). Blank spaces and special characters are allowed in form names, but can result in inconsistent behavior: for example, although you can create a form named test?Form, you cannot retrieve, modify, or delete that form.

Note. Actually you can reference that form. However, you'll need to replace the question mark with the HTTP code %3F; that is, you'll have to use the form name test%3FForm.

action

string

Yes

Specifies the type of action taken by the form. Allowed values are:

• socialRegistration. Equivalent to the socialRegistrationForm form.
• traditionalRegistration. Equivalent to the registrationForm form.
• traditionalSignin. Equivalent to the signIn form.
• passwordReset. Equivalent to the resetPasswordForm form.
• verifyEmail. Equivalent to the resendVerificationForm form.
• profileUpdate. Equivalent to the editProfileForm form
• accountDeactivation. Equivalent to the deactivateAccountForm form.

Saying that the passwordReset action is "equivalent" to the resetPasswordForm form primarily means that you can only add fields to a passwordReset form that are already associated with the resetPasswordForm form.

For example, the currentPassword field is associated with the resetPasswordForm form; that means you can add that field to a form that uses the passwordReset action. However, trying to add the firstName field to a form that uses the passwordReset action fails. That’s because the firstName field is not associated with the resetPasswordForm form.

The action property must be included in the request body or your API call will fail. Note that, after the form has been created you cannot change the action property.

fields

collection

No

JSON collection of the fields associated with the form. For example, the following syntax associates two fields (signInEmailAddress and currentPassword) with the form:

{
  "fields": [
    {
      "name": "signInEmailAddress"
    },
    {
      "name": "currentPassword"
    }
  ]
}
            

validation

collection

No

Validation rules (and custom error messages) invoked when a form is submitted. For example, you can display a custom message if a user enters an invalid password or email address. You can also use these validations to require a user to authenticate before he or she will be allowed to change a specified section of their user profile (such as their password or email address).

Each validation is made up of three sections, one of which (value) is optional:

rule

Name of the validation. Allowed values are:

• requireAuthFields. When enabled, this validation requires a user to authenticate, using the same credentials they used to logon, before he or she can update a specified portion of their user profile. For example, this validation is enabled for use on the changePasswordForm: the user must enter their current password before they are allowed to change that password. The requireAuthFields validation can only be used if the form action is set to profileUpdate.
   
• checkIdentifier. When enabled, this validation checks to see if the email address entered by the user can be found in the user profile store; if it the validation fails, an error message (e.g., “No account can be found that uses that email address”) is displayed.
  
  If you don't enable checkIdentifier then a generic error message (Incorrect username or password) is displayed if either the email address or the password is invalid. The generic message does not distinguish between invalid email addresses or invalid passwords, which helps guard against username enumeration attacks. In those attacks, a hacker continually tries possible email addresses until he or she stumbles upon a valid username.
  
  The checkIdentifier rule is used, by default, on both the forgotPasswordForm and the resetPasswordForm forms. 
  
  Note, too that checkIdentifier can only be used if the form action is set to passwordReset.

Other errors – such as rateLimitExceeded or invalidPassword – might be defined in a flow; if so, these errors can also be used for form validations. However, because these errors represent platform-level configurations that aren’t controlled in the flow, you can only include a validation message; you cannot specify a validation value. This also means that you cannot use the PUT method to enable or disable the validation. All you can do is change the accompanying message.

value

If you're using the checkIdentifier validation, set the value to true to enable the validation or set the value to false to disable the validation. Validations are "fired" only if they are enabled.

If you're using the requireAuthFields validation, set the value to a comma-separated array of all the fields that must be supplied before the form can be processed. 

message

Text of the error message displayed if the validation fails. For example:

"message": "No account with that email address exists."

You can configure a custom message or you can use the ID of an existing translation\ when configuring the message property. For example, this syntax references the existing translation 993a4822d6f93ea9401d5204bb213b35:

"message": "993a4822d6f93ea9401d5204bb213b35"