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

Returns information about the specified form. 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 supports the following methods:


GET

Returns detailed information about the specified form.

URI Parameters

Parameter Type Required Description
form string Yes The form name.
 

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 information about the registrationForm form associated with the documentation flow.


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

      Running this command in Postman

Responses

200 OK

Response Example (application/json)

{
    "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms/signInForm",
    "action": "traditionalSignin",
    "fields": [
      {
        "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/fields/signInEmailAddress",
        "name": "signInEmailAddress",
        "required": true     },
      {
       "_self": "/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/fields/currentPassword",
       "name": "currentPassword",
       "required": false
      }
    ] 
} 

404 Not Found

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

Response Example (application/json)


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


PUT

Description

Modifies the property values associated with a form. 

Form properties, which must be specified (in JSON format) in the request body of your API call, include the following:

Property Datatype Required Description

action

string

Yes

Specifies the type of action taken by the form. The action property must be included in the request body, but you cannot change the value already assigned to this 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 is 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.
     
  • checkIdentifiercheckIdentifier. 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.

    This 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 will "fire" 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. I

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"

Two notes regarding the PUT method. First, even though you can include the name property in your request body, that property (and property value) will be ignored. For example, suppose you have a form named testForm and you include this value in your request body:

"name": "newFormName"

When your API call completes, the form will still be named testForm: you cannot rename a form.

Second, when you call this method the values included in your request body replace the existing form values. For example, suppose you have a form with two fields:

  • firstName
  • lastName

You now make an API call where the request body has only one field:

  "fields": [
    {
      "name": "middleName"
    }
  ]

That API call will not append middleName to your list of fields. Instead, the specified field will replace the previous set of fields, meaning that your form now has only one field:

  • middleName

To add middleName to your field list you must include the previous fields as well:

  "fields": [
    {
      "name": "firstName"
    },
    {
      "name": "lastName"
    },
    {
      "name": "middleName"
    }
  ]

Oh, and be sure to include all the other properties (for example, any validations you might have added) that currently exist in the form a well: if you don’t, those properties and property values will be deleted when the form is deleted.

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 adds three fields (signInEmailAddresscurrentPassword, and displayName) to the signInForm associated with the documentation flow.


curl -X PUT \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms/signInForm \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg=' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "traditionalSignin",
    "fields": [
        {
            "name": "signInEmailAddress"
        },
        {
            "name": "currentPassword"
        },
         {
            "name": "displayName"
        }
    ]
}'
      Running this command in Postman

Responses

204 No Content

If the form is successfully modified no data will be returned. Instead, you will see the HTTP status code 204 No Content.

404 Not Found

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

Response Example (application/json)


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

DELETE

Description

Removes the specified form. Note that calling this endpoint only removes the form. Other components associated with the form (such as fields) are not deleted.

Authentication

This endpoint supports Basic authentication. 

How to Create an Authentication String

Request Example (application/json)


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

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)

The following command deletes the form testForm from the documentation flow:


curl -X DELETE \
  https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/documentation/forms/testForm \
  -H 'Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg='
  
      Running this command in Postman

Responses

204 No Content

If the form is deleted no data will be returned. However, you will see the HTTP status code 204 No Content.

404 Not Found

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

Response Example (application/json)


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