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
- POST
GET
Returns a collection of all the forms in a flow.
API Client Permissions
The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:
owner | access_issuer | direct_access | direct_read_access | login_client |
Yes | No | Yes | No | No |
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. |
action | string | Yes | Specifies the type of action taken by the form. Allowed values are:
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:
|
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:
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. 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. message Text of the error message displayed if the validation fails. For example:
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:
|
API Client Permissions
The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:
owner | access_issuer | direct_access | direct_read_access | login_client |
Yes | No | Yes | No | No |
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."
}