The forms API, which supports the form builder interface in the PingOne Admin Console, provides tools for administrators to create custom forms presented to users during the authentication workflow. This capability allows administrators to:

The forms API provides endpoints to create, read, update, and delete form builder resources.

Forms category types

The API allows the following form types:

Forms data model

Property Description
created The time the resource was created.
category A string that specifies the type of custom-defined form. Options are REGISTRATION, SELF_SERVICE, PROGRESSIVE_PROFILING, and CUSTOM. The CUSTOM and REGISTRATION form types allow the form to be built with fields that do not map specifically to the PingOne directory attributes. This is a required property.
cols An integer that specifies the number of columns in the form.
components An object that specifies the form configuration elements.
description A string that specifies the description of the population.
id A string that specifies the resource’s unique identifier.
markOptional A boolean that specifies whether optional fields are highlighted in the rendered form. This is a required property.
markRequired A boolean that specifies whether required fields are highlighted in the rendered form. This is a required property.
modified The time the resource was last updated.
name A string that specifies the form name, which must be provided and must be unique within an environment. This is a required property.

Form components data model

Property Description
button A form button object that contains the button text. This is a required property.
button.text A string that specifies the form button text. This is a required property.
fields A list of form fields that specifies the form fields that make up the form. Options include text inputs, passwords, radio buttons, checkboxes, dropdowns, headers, and dividers. This is a required property.

FormField data model

When the form field is TEXT, PASSWORD, RADIO, CHECKBOX, or DROPDOWN, then a FormElement is created and validated.

When the form field is DIVIDER, PARAGRAPH, or EMPTY_FIELD, then a FormItem is created and validated.

When the form field is PASSWORD_VERIFY, then a FormElementPasswordVerify is created and validated.

Property Description
position An object containing field position information. This is a required property.
position.col An integer that specifies the column position of the field. This is a required property.
position.row An integer that specifies the row position of the field. This is a required property.
position.width An integer that specifies the width of the field.
type A string that specifies the type of the field. Options are TEXT, PASSWORD, PASSWORD_VERIFY, RADIO, CHECKBOX, DROPDOWN, DIVIDER, EMPTY_FIELD, and TEXTBLOB. This is a required property.

FormElement data model

Property Description
key A string that specifies the field unique key for the HTML name attribute. This is a required property.
label A string that specifies the field label. This is a required property.
layout A string that specifies layout attributes for radio button and checkbox fields. Options are HORIZONTAL or VERTICAL. This is a required property when the type is RADIO or CHECKBOX.
options An array of strings that specifies the unique list of options. This is a required property when the type is RADIO, CHECKBOX, or DROPDOWN.
required A boolean that specifies whether the field is required. This is a required property.
validation An object containing validation data for the field. This is a required property when the type is TEXT.
validation.regex A string that specifies a validation regular expression. The expression must be a valid regular expression string. This is a required property when the validation type is CUSTOM.
validation.type A string that specifies the validation type. Options are NONE and CUSTOM. This is a required property when the field type is TEXT.
validation.errorMessage A string that specifies the error message to be displayed when the field validation fails.

FormElementPasswordVerify data model

The FormElementPasswordVerify object is an extension of FormElement and contains all of the same fields in FormElement as well as those listed below.

Property Description
labelPasswordVerify A string that verifies password field label.

FormItem data model

Property Description
content A string that specifies the field content (for example, HTML when the field type is TEXTBLOB.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.