PingOne Platform APIs

Forms

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:

  • Define the interactive fields and the corresponding data to be collected during a registration or sign-on flow, which could include text inputs, checkboxes, dropdowns, and radio buttons.

  • Define the user experience that they want to deliver to the customer, such as field ordering, labeling, control over input validation and error feedback, and support for contextual or formatting items such as text (headers, explanatory text), and dividers.

The supported CUSTOM form type gives you the flexibility to create custom forms without having to write HTML. This type also allows the form to be built with fields that do not map specifically to PingOne directory attributes. You can create forms for registration, password reset, password recovery, and many other use cases.

Translatable keys

You can add translatable keys for any user-facing text in your forms, including the input field labels, button labels, and rich text. After adding these keys, the text can be translated based on the end user’s browser settings for preferred languages.

After you have added translatable keys, you must configure which languages are enabled for translation (refer to Language Management).

Forms data model

Property Type Required? Mutable? Description

created

Date

N/A

Read-only

The date the resouce was created (ISO-8061 format).

category

String

Required

Mutable

A string that specifies the type of 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 property is read-only for updates.

cols

Integer

Optional

Mutable

An integer that specifies the number of columns in the form (min = 1; max = 4).

components

Object

Required

Mutable

An object that specifies the form configuration elements.

description

String

Optional

Mutable

A string that specifies the description of the form.

embedded

Object

N/A

Read-only

An object that specifies the list of forms resources (and their properties) associated with the current environment.

environment.id

String

N/A

Read-only

A string that specifies the environment’s unique identifier.

fieldTypes

Object

Optional

Read-only

A read-only object that specifies the list of the FormField types in the form. For details, refer to FormField data model.

id

String

N/A

Read-only

A string that specifies the resource’s unique identifier.

languageBundle

Object

Optional

Mutable

An object that provides a map of i18n keys to their translations. This object includes both the keys and their default translations. The PingOne language management service finds this object, and creates the new keys for translation for this form.

markOptional

Boolean

Required

Mutable

A boolean that specifies whether optional fields are highlighted in the rendered form.

markRequired

Boolean

Required

Mutable

A boolean that specifies whether required fields are highlighted in the rendered form.

modified

Date

N/A

Read-only

The time the resource was last updated.

name

String

Required

Mutable

A string that specifies the form name, which must be provided and must be unique within an environment.

passwordAutoCompleteEnabled

Boolean

Required

Mutable

A boolean that specifies whether the password auto-complete feature is enabled.

showPasswordRequirements

Boolean

Optional

Mutable

A boolean that specifies whether to return the password requirements during a DaVinci flow. A form with a new password field does not show the password policy information automatically in the response. To return the password policy information, the value of this property must be set to true.

textAutoCompleteEnabled

Boolean

Required

Mutable

A boolean that specifies whether the text auto-complete feature is enabled.

translationMethod

String

Optional

Mutable

A string that specifies how to translate the text strings in the form. Options are TRANSLATE, DEFAULT_VALUE (to omit translating the form), and KEY (for debugging the form).

Form components data model

Property Type Required? Mutable? Description

fields

Object

Required

Mutable

A list of form fields that specifies the form fields that make up the form.

FormField data model

  • FormElement represents a FormField of types TEXT, PASSWORD, RADIO, CHECKBOX, DROPDOWN, COMBOBOX.

  • FormItemWithIcon represents a FormField of type SLATE_TEXTBLOB.

  • FormElementPasswordVerify represents a FormField of type PASSWORD_VERIFY.

  • FormSubmit represents a FormField of type SUBMIT_BUTTON.

  • FormFlowLink represents FormField of type FLOW_LINK.

  • FormFlowButton represents a FormField of type FLOW_BUTTON.

  • FormRecaptchaV2 represents a FormField of type RECAPTCHA_V2.

  • FormQrCode represents a FormField of type QR_CODE.

  • FormPolling represents a FormField of type POLLING.

  • FormFIDO2 represents a FormField of type FIDO2.

  • FormAgreement represents a FormField of type AGREEMENT.

Property Type Required? Mutable? Description

position

Object

Required

Mutable

An object containing field position information.

position.col

Integer

Required

Mutable

An integer that specifies the number of columns (min = 1; max = 4).

position.row

Integer

Required

Mutable

An integer that specifies the number of rows (maximum number is 50).

position.width

Integer

Optional

Mutable

An integer that specifies the width of the field (in percentage).

type

String

Required

Mutable

A string that specifies the type of the field. Options are TEXT, PASSWORD, PASSWORD_VERIFY, PHONE_NUMBER, RADIO, CHECKBOX, DROPDOWN, COMBOBOX, DIVIDER, EMPTY_FIELD, TEXTBLOB (Deprecated), SLATE_TEXTBLOB, SUBMIT_BUTTON, ERROR_DISPLAY, FLOW_LINK, FLOW_BUTTON, SOCIAL_LOGIN_BUTTON, and RECAPTCHA_V2, QR_CODE, DEVICE_ENROLLMENT, DEVICE_REGISTRATION, DEVICE_AUTHENTICATION, POLLING, FIDO2, SINGLE_CHECKBOX, AGREEMENT.

visibility

Object

Optional

Mutable

An object that specifies the visibility settings for a form field.

visibility.type

String

Optional

Mutable

A string that specifies the visibility behavior for the field. Options are ALWAYS_VISIBLE, SHOW_BY_DEFAULT, and HIDE_BY_DEFAULT. If visibility is set, this property is required.

visibility.key

String

Optional

Mutable

A non-unique string associated with the field when visibility is evaluated by DaVinci at runtime. If the visibility.type property is set to SHOW_BY_DEFAULT or HIDE_BY_DEFAULT, then this property is required.

FormElement data model

Property Type Required? Mutable? Description

isAttributeDisabled

Boolean

Optional

Read-only

A boolean that specifies whether the linked directory attribute is disabled.

key

String

Required

Mutable

A string that specifies a unique identifier for the FormElement in the list.

label

String

Optional

Mutable

A string that specifies the field’s label.

labelMode

String

Optional

Mutable

A string that specifies how the label is rendered. Options are DEFAULT and FLOAT.

layout

String

Optional

Mutable

The layout orientation associated with the element. Options are HORIZONTAL and VERTICAL. This property is required when the element type is RADIO or CHECKBOX.

options

Array[]

Optional

Mutable

An array of strings that specifies the unique list of options. This is a required property when the type is RADIO, CHECKBOX, COMBOBOX, or DROPDOWN. The POST endpoint accepts a list of strings, at which will create a list of FormElementOptions with matching labels and values.

otherOptionEnabled

Boolean

Optional

Mutable

A boolean that specifies whether other options are available, enabling users to specify a custom value that is not one of the predefined options. This property is valid for RADIO, CHECKBOX, or DROPDOWN types.

otherOptionKey

String

Optional

Mutable

A string that specifies the key associated with the other option.

otherOptionlabel

String

Optional

Mutable

A string that specifies the label for a custom or "other" choice in a list.

otherOptionInputlabel

String

Optional

Mutable

A string that specifies the label placeholder text for the other option.

otherOptionAttributeDisabled

Boolean

Optional

Mutable

A boolean that specifies whether the other option is disabled.

required

Boolean

Required

Mutable

A boolean that specifies whether the field is required.

validation

Object

Optional

Mutable

An object containing validation data for the field. This is a required property when the type is TEXT.

validation.regex

String

Optional

Mutable

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

String

Optional

Mutable

A string that specifies the validation type. Options are NONE, EMAIL, and CUSTOM. This is a required property when the field type is TEXT.

validation.errorMessage

String

Optional

Mutable

A string that specifies the error message to be displayed when the field validation fails.

FormElementOption data model

Property Type Required? Mutable? Description

label

String

Required

Mutable

A string that specifies the label shown to the end user for this option.

value

String

Required

Mutable

A string that specifies the value of the field if this option is selected.

FormItem data model

Property Type Required? Mutable? Description

content

String

Optional

Mutable

A string that specifies the field content.

FormItemWithIcon data model

Property Type Required? Mutable? Description

icon.type

String

Required

Mutable

A string that specifies the icon type. Options are NONE, AGREEMENT, ALERT, CALL, FAILURE, FINGERPRINT, LINK, MAIL, MOBILE_PHONE, PASSKEY, SUCCESS, QR_CODE, TEXT_MESSAGE, and USB_KEY.

icon.size

String

Required

Mutable

A string that specifies the icon size. Options are SMALL, MEDIUM, and LARGE.

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 Type Required? Mutable? Description

labelPasswordVerify

String

Optional

Mutable

A string that specifies the label for the verify password field.

FormSubmit and FormFlowButton data model

Property Type Required? Mutable? Description

label

String

Required

Mutable

A string that specifies the button label.

styles.width

Integer

Optional

Mutable

An integer that specifies the button width.

styles.WidthUnit

Integer

Optional

Mutable

An integer that specifies the button width unit. Options are PERCENT and PIXELS.

styles.alignment

String

Optional

Mutable

A string that specifies the button alignment. Options are LEFT, RIGHT, and CENTER.

styles.padding

Object

Optional

Mutable

A string that specifies the button padding. Options are styles.padding.top, styles.padding.left, styles.padding.right, and styles.padding.bottom.

styles.padding.top

Integer

Optional

Mutable

A string that specifies the top padding. Value must be between -100 to 100.

styles.padding.left

Integer

Optional

Mutable

A string that specifies the left padding. Value must be between -100 to 100.

styles.padding.right

Integer

Optional

Mutable

A string that specifies the right padding. Value must be between -100 to 100.

styles.padding.bottom

Integer

Optional

Mutable

A string that specifies the bottom padding. Value must be between -100 to 100.

styles.backgroundColor

String

Optional

Mutable

A string that specifies the button background color. The value must be a valid hexadecimal color.

styles.textColor

String

Optional

Mutable

A string that specifies the button text color. The value must be a valid hexadecimal color.

styles.borderColor

String

Optional

Mutable

A string that specifies the button border color. The value must be a valid hexadecimal color.

styles.enabled

Boolean

Optional

Mutable

A boolean that specifies whether the button is enabled.

styles.displayDefaultThemeButtonBackgroundColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s background color.

styles.displayDefaultThemeButtonBorderColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s border color.

styles.displayDefaultThemeButtonTextColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s text color.

FormLinkCustom data model

Property Type Required? Mutable? Description

label

String

Required

Mutable

A string that specifies the link label.

styles.alignment

String

Optional

Mutable

A string that specifies the link alignment. Options are LEFT, RIGHT, and CENTER.

styles.textColor

String

Optional

Mutable

A string that specifies the link text color. The value must be a valid hexadecimal color.

styles.enabled

Boolean

Optional

Mutable

A boolean that specifies whether the link is enabled.

styles.padding

Object

Optional

Mutable

A string that specifies the link padding. Options are styles.padding.top, styles.padding.left, styles.padding.right, and styles.padding.bottom.

styles.padding.top

Integer

Optional

Mutable

A string that specifies the top padding. Value must be between -100 to 100.

styles.padding.left

Integer

Optional

Mutable

A string that specifies the left padding. Value must be between -100 to 100.

styles.padding.right

Integer

Optional

Mutable

A string that specifies the right padding. Value must be between -100 to 100.

styles.padding.bottom

Integer

Optional

Mutable

A string that specifies the bottom padding. Value must be between -100 to 100.

styles.displayDefaultThemeLinkColor

Boolean

Optional

Mutable

A boolean that specifies whether the default theme’s link color is enabled.

FormReCAPTCHA V2 data model

Property Type Required? Mutable? Description

size

String

Required

Mutable

A string that specifies the reCAPTCHA size. Options are NORMAL and COMPACT.

theme

String

Required

Mutable

A string that specifies the reCAPTCHA theme. Options are LIGHT and DARK.

alignment

String

Required

Mutable

A string that specifies the reCAPTCHA alignment. Options are LEFT, RIGHT, and CENTER.

FormQrCode data model

Property Type Required? Mutable? Description

alignment

String

Required

Mutable

A string that specifies the QR code alignment. Options are LEFT, RIGHT, and CENTER.

size

String

Required

Mutable

A string that specifies the QR code size. Options are SMALL, MEDIUM, and LARGE.

fallbackText

String

Optional

Mutable

A string that specifies the text label for fallback under the QR code.

FormPolling data model

Property Type Required? Mutable? Description

pollingAppearance

String

Required

Mutable

A string that specifies the polling activity indicator appearance. Options are NONE, DOTS, and SPINNER.

size

String

Required

Mutable

A string that specifies the polling activity indicator size. Options are SMALL, MEDIUM, and LARGE.

FormFIDO2 data model

Property Type Required? Mutable? Description

trigger

String

Required

Mutable

A string that specifies the FIDO2 UI trigger type. Options are BUTTON and AUTOMATIC.

action

String

Required

Mutable

A string that specifies the FIDO2 action. Options are REGISTER and AUTHENTICATE.

label

String

Required

Mutable

A string that specifies the text label for the FIDO2 button.

SingleCheckbox data model

Property Type Required? Mutable? Description

appearance

String

Required

Mutable

A string that specifies the checkbox appearance. Options are CHECKBOX and SWITCH.

errorMessage

String

Optional

Mutable

A string that specifies the message to display if validation fails.

inputType

String

Required

Mutable

A string that specifies the type of field. Value should be set to BOOLEAN.

FormAgreement data model

Property Type Required? Mutable? Description

inputType

String

Required

Mutable

A string that specifies the type of field. Value should be set to READ_ONLY_TEXT.

titleEnabled

Boolean

Required

Mutable

Specifies whether the title is enabled.

agreement.id

String

Optional

Mutable

An identifier that specifies the ID of the agreement.

agreement.useDynamicAgreement

Boolean

Optional

Mutable

An agreement option that specifies whether to use the agreement identified in the DaVinci form node.

PingOne prevents the use of multiple FormAgreement components per form.

FormSocialLoginButton data model

Property Type Required? Mutable? Description

idpName

String

Required

Mutable

A string that specifies the external identity provider name.

idpType

String

Required

Mutable

A string that specifies the external identity provider type. Options are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.

idpId

String

Required

Mutable

A string that specifies the external identity provider’s ID.

idpEnabled

Boolean

Optional

Mutable

A boolean that specifies whether the external identity provider is enabled.

iconSrc

String

Optional

Mutable

A string that specifies the external edentity provider’s image icon URL.

label

String

Required

Mutable

A string that specifies the social login button label.

styles.alignment

String

Optional

Mutable

A string that specifies the social login button alignment. Options are LEFT, RIGHT, and CENTER.

styles.textColor

String

Optional

Mutable

A string that specifies the social login button text color.

styles.enabled

Boolean

Optional

Mutable

A boolean that specifies whether the social login button is enabled.

styles.width

Integer

Optional

Mutable

An integer that specifies the button width.

styles.widthUnit

Integer

Optional

Mutable

An integer that specifies the button width unit. Options are PERCENT and PIXELS.

styles.padding

Object

Optional

Mutable

A string that specifies the button padding. Options are styles.padding.top, styles.padding.left, styles.padding.right, and styles.padding.bottom.

styles.padding.top

Integer

Optional

Mutable

A string that specifies the top padding. Value must be between -100 to 100.

styles.padding.left

Integer

Optional

Mutable

A string that specifies the left padding. Value must be between -100 to 100.

styles.padding.right

Integer

Optional

Mutable

A string that specifies the right padding. Value must be between -100 to 100.

styles.padding.bottom

Integer

Optional

Mutable

A string that specifies the bottom padding. Value must be between -100 to 100.

idpType

String

Required

Mutable

A string that specifies the external identity provider type. Options are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, and SAML.

styles.textColor

String

Optional

Mutable

A string that specifies the button text color. The value must be a valid hexadecimal color.

styles.borderColor

String

Optional

Mutable

A string that specifies the button border color. The value must be a valid hexadecimal color.

styles.enabled

Boolean

Optional

Mutable

A boolean that specifies whether the button is enabled.

styles.displayDefaultThemeButtonBackgroundColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s background color.

styles.displayDefaultThemeButtonBorderColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s border color.

styles.displayDefaultThemeButtonTextColor

Boolean

Optional

Mutable

A boolean that specifies whether the button uses the default theme’s text color.

width

Integer

Optional

Mutable

An integer that specifies the button width.

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.