PingOne Platform APIs

Forms

  • 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).

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

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

Optional

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

Optional

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.

  • FormElementPassword represents a FormField of type PASSWORD.

  • FormSubmit represents a FormField of type SUBMIT_BUTTON.

  • FormLinkCustom 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.

  • FormImage represents a FormField of type IMAGE.

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.

FormFieldWithKey data model

The FormFieldWithKey object is an extension of FormField and contains all of the same fields in the FormField data model as well as those listed below.

Property Type Required Mutable Description

key

String

Required

Mutable

A unique identifier for the FormField in the list.

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.

FormItemWithOptionalKey data model

Property Type Required Mutable Description

key

String

Optional

Mutable

A string that specifies the field content.

FormItemWithIcon data model

The FormItemWithIcon object is an extension of FormItemWithOptionalKey and contains all of the same fields in the FormItemWithOptionalKey data model as well as those listed below.

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.

FormElementPassword data model

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

Property Type Required Mutable Description

showPasswordRequirements

Boolean

Optional

Mutable

Specifies whether the form component will show the password requirement.

FormElementPasswordVerify data model

The FormElementPasswordVerify object is an extension of FormElement and contains all of the same fields in the FormElement data model 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.

FormPhoneNumber data model

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

Property Type Required Mutable Description

defaultCountryCode

String

Optional

Mutable

A two-character country code to use as the default selection.

countryCodeLabel

String

Optional

Mutable

Label for the country code field.

validatePhoneNumber

Boolean

Optional

Mutable

Specifies whether to validate the phone number format. The default is true.

showExtension

Boolean

Optional

Mutable

Specifies whether to show the phone number extension field.

extensionLabel

String

Optional

Mutable

Label for the phone number extension field. Required if showExtension is set to true.

FormDeviceRegistration data model

The FormDeviceRegistration object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

Property Type Required Mutable Description

label

String

Required

Mutable

Label for the device registration field.

options

Array[]

Required

Mutable

An array of objects that specifies the list of devices available for registration. Must not be empty.

required

Boolean

Optional

Mutable

Specifies whether the field is required.

FormDeviceAuthentication data model

The FormDeviceAuthentication object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

Property Type Required Mutable Description

label

String

Required

Mutable

Label for the device authentication field.

options

Array[]

Required

Mutable

An array of objects that specifies the list of devices available for authentication. Must not be empty

required

Boolean

Optional

Mutable

Specifies whether the field is required.

FormSubmit and FormFlowButton data model

Property Type Required Mutable Description

label

String

Required

Mutable

A string that specifies the button label.

key

String

Required

Mutable

A string that specifies the field content.

This value is only required for FormFlowButton.

styles.height

Integer

Optional

Mutable

An integer that specifies the button height.

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

The FormLinkCustom object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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

The FormQrCode object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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

The FormPolling object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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

The FormFIDO2 object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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.

styles.width

Integer

Optional

Mutable

Specifies button width.

styles.height

Integer

Optional

Mutable

Specifies button height.

styles.widthUnit

String

Optional

Mutable

Specifies the button width unit. Options are PERCENT with values from 1-100 and PIXELS with values from 1-1000.

styles.alignment

String

Optional

Mutable

Specifies the button alignment. Options are LEFT, RIGHT, and CENTER.

styles.padding

Object

Optional

Mutable

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

Specifies the top padding. Value must be between -100 to 100.

styles.padding.left

Integer

Optional

Mutable

Specifies the left padding. Value must be between -100 to 100.

styles.padding.right

Integer

Optional

Mutable

Specifies the right padding. Value must be between -100 to 100.

styles.padding.bottom

Integer

Optional

Mutable

Specifies the bottom padding. Value must be between -100 to 100.

styles.backgroundColor

String

Optional

Mutable

Specifies the button background color. The value must be a valid hexadecimal color.

styles.textColor

String

Optional

Mutable

Specifies the button text color. The value must be a valid hexadecimal color.

styles.borderColor

String

Optional

Mutable

Specifies the button border color. The value must be a valid hexadecimal color.

styles.enabled

Boolean

Optional

Mutable

Specifies whether the button is enabled.

styles.displayDefaultThemeButtonBackgroundColor

Boolean

Optional

Mutable

Specifies whether the button uses the default theme’s background color.

styles.displayDefaultThemeButtonBorderColor

Boolean

Optional

Mutable

Specifies whether the button uses the default theme’s border color.

styles.displayDefaultThemeButtonTextColor

Boolean

Optional

Mutable

Specifies whether the button uses the default theme’s text color.

required

Boolean

Optional

Mutable

Specifies whether the field is required.

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

The FormAgreement object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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

The FormSocialLogin object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

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.enabled

Boolean

Optional

Mutable

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

styles.height

Integer

Optional

Mutable

An integer that specifies the button height.

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.

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.backgroundColor

String

Optional

Mutable

The button background color. The value must be a valid hexadecimal color.

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.

FormDividerCustom data model

The FormDividerCustom object is an extension of FormField and contains all of the same fields in the FormField data model as well as those listed below.

Property Type Required Mutable Description

label

String

Optional

Mutable

The component label.

key

String

Optional

Mutable

The component key.

styles.alignment

String

Optional

Mutable

The divider alignment. Options are LEFT, RIGHT, and CENTER.

FormImage data model

The FormImage object is an extension of FormFieldWithKey and contains all of the same fields in the FormFieldWithKey data model as well as those listed below.

Parameter Type Required Mutable Description

description

String

No

Mutable

A string that specifies an optional description for the image used as alt text. Supports translatable text.

imageSource

String

Yes

Mutable

A string that specifies the image source. Options are URL or FORM_NODE. Use FORM_NODE when the image URL will be provided at runtime through the Forms connector.

imageUrl

String

Conditional

Mutable

A string that specifies the image URL. Required when imageSource is URL. The value must be a valid http/https URL.

styles

FormImageStyles

No

Mutable

An object that specifies optional style configuration for the image, including size, dimensions, padding, and alignment.

enableHyperlink

Boolean

No

Mutable

A boolean that specifies whether clicking the image opens a hyperlink.

hyperlinkSource

String

Conditional

Mutable

A string that specifies the hyperlink source. Options are URL or FORM_NODE. Required when enableHyperlink is true. Use FORM_NODE when the hyperlink URL will be provided at runtime through the Forms connector.

hyperlinkUrl

String

Conditional

Mutable

A string that specifies the hyperlink target URL. Required when enableHyperlink is true and hyperlinkSource is URL. Must be a valid http/https URL.

openInNewTab

Boolean

No

Mutable

A boolean that specifies whether the hyperlink opens in a new browser tab. Defaults to true.

enableCustomAttributes

Boolean

No

Mutable

A boolean that specifies whether the image element supports custom HTML attributes.

customAttributes

FormImageCustomAttributes

No

Mutable

An object that specifies optional custom HTML attributes for the image element.

FormImageStyles data model

Parameter Type Required Mutable Description

size

String

Yes

Mutable

A string that specifies the image sizing mode. Options are FIT, SMALL, MEDIUM, LARGE, or CUSTOM. Defaults to FIT.

  • FIT: width auto, height auto, maxWidth 100%, maxHeight 100%

  • SMALL: maxWidth 72px; maxHeight 72px

  • MEDIUM: maxWidth 128px; maxHeight 128px

  • LARGE: maxWidth 256px; maxHeight 256px

  • CUSTOM: uses maxWidth and maxHeight with their specified units

maxHeight

Integer

No

Mutable

An integer that specifies the maximum image height. Must be at least 1 when provided.

maxHeightUnit

String

Conditional

Mutable

A string that specifies the unit for maxHeight. Options are PIXELS or PERCENT. Required when maxHeight is provided.

maxWidth

Integer

No

Mutable

An integer that specifies the maximum image width. Must be at least 1 when provided.

maxWidthUnit

String

Conditional

Mutable

A string that specifies the unit for maxWidth. Options are PIXELS or PERCENT. Required when maxWidth is provided.

paddingPreset

String

Yes

Mutable

A string that specifies the padding preset. Options are NONE, COMPACT, COMFORTABLE, or CUSTOM. Defaults to COMFORTABLE.

  • NONE: top/right/bottom/left 0px

  • COMPACT: top/right/bottom/left 5px

  • COMFORTABLE: top/right/bottom/left 20px

  • CUSTOM: uses the values specified in padding

padding

object

No

Mutable

An object that specifies the padding values for the image, including top, right, bottom, and left. Used when paddingPreset is CUSTOM. If a custom side isn’t provided at render time, it falls back to 20px.

alignment

String

No

Mutable

A string that specifies the image alignment. Options are LEFT, RIGHT, or CENTER. Defaults to CENTER.

Padding data model

Property Type Required Mutable Description

top

Integer

No

Mutable

A string that specifies the top padding value.

right

Integer

No

Mutable

An integer that specifies the right padding value.

bottom

Integer

No

Mutable

An integer that specifies the bottom padding value.

left

Integer

No

Mutable

An integer that specifies the left padding value.

FormImageCustomAttributes data model

Property Type Required Mutable Description

id

String

No

Mutable

A string that specifies the custom HTML id attribute for the image element.

class

String

No

Mutable

A string that specifies the custom HTML class attribute for the image element.

referrerPolicy

String

No

Mutable

A string that specifies the referrer policy for the image request. Options are no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, or unsafe-url.

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.