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

Returns information about all the forms associated with a flow. Forms are containers for fields, and play a large role in dictating the information presented to users during activities such as login and registration.

This endpoint includes the following methods:


GET

Returns a collection of all the forms in a flow.

Authentication

This endpoint supports Basic authentication. 

How to Create an Authentication String

Base URL

The base URL for this endpoint is your Configuration API domain followed by /config/ followed by your application ID. For example, if you are in the US region and your application ID is htb8fuhxnf8e38jrzub3c7pfrr, then your base URL would be:


https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn
  • sg

Sample Request (curl)

This command returns all the forms associated with the documentation flow.


curl -G \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg='

      Running this command in Postman

Responses

200 OK

Response Example (application/json)


[
  {
    "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms/signInForm",
    "name": "signInForm"
  },
  {
    "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms/editProfileForm",
    "name": "editProfileForm"
  }
]
                                                            

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)


{
  "errors": "Flow not found."
}
                                                            
 


POST

Description

Creates a new form and associates that form with an existing flow. 

To create a new form, you must specify the properties for the form (using JSON: JavaScript Object Notation) in the request body of your API call. Those properties include the following:

Property Datatype Required Description

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"

Authentication

This endpoint supports Basic authentication. 

How to Create an Authentication String

Base URL

The base URL for this endpoint is your Configuration API domain followed by /config/ followed by your application ID. For example, if you are in the US region and your application ID is htb8fuhxnf8e38jrzub3c7pfrr, then your base URL would be:


https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr

Allowed regions are:

  • us 
  • eu 
  • au 
  • sa 
  • cn
  • sg

Sample Request (curl)

This command creates a new form (testForm) associated with the standard flow and the application hevwjvt8j7cym5hbbzdu8mv6aj.


curl -X POST \
  https://v1.api.us.janrain.com/config/hevwjvt8j7cym5hbbzdu8mv6aj/flows/standard/forms \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "testForm",
    "action": "passwordReset",
    "fields": [
      {
        "name": "signInEmailAddress"
      }
    ]
  "validation": [
    {
      "rule": "checkIdentifier",
      "value": true,
      "message": "We'\''re sorry, but we don'\''t recognize that email address."
    }
    ]
  }
  '
      Running this command in Postman

Responses

200 OK

If your API call succeeds your response includes the property values for the new form.

Response Example (application/json)


{
  "action": "passwordReset",
  "fields": [
    {
      "_self": "/config/hevwjvt8j7cym5hbbzdu8mv6aj/flows/standard/fields/signInEmailAddress",
      "name": "signInEmailAddress",
      "required": true
    }
  ],
  "validation": [
    {
      "rule": "checkIdentifier",
      "value": true,
      "message": "We're sorry, but we don't recognize that email address."
    }
  ],
  "_self": "/config/hevwjvt8j7cym5hbbzdu8mv6aj/flows/standard/forms/newTestForm"
}

404 Not Found

Flow could not be found. Please check the value and try again.

Response Example (application/json)


{
  "errors": "Flow not found."
}