--- title: "Update form" method: PATCH path: "/forms/{formID}" tags: ["Forms"] --- # Update form `PATCH /forms/{formID}` ## Request - Base URL: `https://api.omnisend.com/api` - URL: `https://api.omnisend.com/api/forms/{formID}` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `forms.write` - API key in header `Authorization` Partially update a form. Only the fields present in the request body are changed; omitted fields are left unchanged. Nested objects must be sent complete, as they fully replace the stored value. Sending `null` for an optional field clears it, while sending `null` for a mandatory field is rejected. Form status and creation origin cannot be changed through this endpoint. **Games:** a `mysteryBox` or `scratchCard` block adds an interactive game to the form. A form may contain at most one game, it cannot be combined with a wheel of fortune, and the game's step must be placed before or at the first step containing a required email or phone field. The game reward is revealed to the visitor through a `discount` block of type `game` on the success step. **Scopes:** `forms.write` **Rate Limiting:** This endpoint is rate limited to 40 requests per minute. ## Path parameters - `formID` string, required ## Headers - `Omnisend-Version` string, required ## Request body - UpdateFormRequest: Request body for updating a form. Only `formID` (path) is mandatory; every body field is optional. Provided fields fully replace the stored value (nested objects must be sent complete); omitted fields are left unchanged. Sending `null` for a mandatory field (`name`, `displayType`, `content`, `targeting`) is rejected. Sending `null` for an optional field clears the stored value. Form status cannot be changed through this endpoint. - `autoRedirect` FormAutoRedirect: Auto-redirect configuration shown after a successful submission. - `countdownText` string: Text shown during the redirect countdown - `delayMs` integer: Delay before redirecting, in milliseconds. Range: 1000-60000 - `isEnabled` boolean: Whether auto-redirect is enabled - `shouldOpenInNewTab` boolean: Whether the redirect opens in a new tab - `url` string: URL to redirect to after submission - `clickOutside` FormClickOutside: Click-outside-to-close behavior configuration. - `isEnabled` boolean: Whether clicking outside the form closes it - `contactTags` string[], nullable: Tags applied to contacts who submit the form - `content` FormContent: Form content submitted when creating a form: general settings, steps, and optional success/subscribed/unavailable steps. - `generalSettings` FormGeneralSettings, required: General presentation settings shared across a form: content, body, link, presets, and field styles. - `backgroundImage` FormBackgroundImage: Background image configuration. - `fit` 'cover' | 'contain': Background image fit - `id` string, required: ID references an existing image in the Images API. - `padding` string: Background image padding in pixels or percent - `position` 'left' | 'right' | 'top' | 'back': Background image position - `size` string: Background image size in pixels or percent - `body` FormBody, required: Form body (container) presentation. - `backgroundColor` string: Body background color - `borderColor` string: Body border color - `borderRadius` string, required: Body border radius in pixels - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Body border style - `borderWidth` string, required: Body border width in pixels - `buttonPresets` FormButtonPreset[], required: Named button style presets - `id` 'primary_button' | 'secondary_button' | 'tertiary_button', required: Preset identifier - `name` string: Preset name - `styles` FormButtonStyle, required: Styling applied to a button preset. - `backgroundColor` string: Button background color - `borderColor` string: Button border color - `borderRadius` string, required: Button border radius in pixels. Range: 0-50 - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Button border style - `borderWidth` string, required: Button border width in pixels - `color` string, required: Button text color - `fontFamily` string, required: Button font family - `fontSize` string, required: Button font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal', required: Button font style - `fontWeight` 'bold' | 'normal', required: Button font weight - `hoverBackgroundColor` string: Button background color on hover - `hoverBorderColor` string: Button border color on hover - `hoverColor` string: Button text color on hover - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `textAlign` 'left' | 'center' | 'right': Button text alignment - `textDecoration` 'underline' | 'none', required: Button text decoration - `closeButton` FormCloseButton: Close button appearance. - `backgroundColor` string: Close button background color - `color` string, required: Close button color - `isVisible` boolean: Whether the close button is visible - `content` FormContentSettings, required: Form container dimensions and overlay color. - `color` string, required: Overlay color behind the form - `width` string, required: Form container width in pixels - `fieldStyles` FormFieldStyles, required: Styling shared across form input fields. - `errorColor` string, required: Validation error text color - `field` FormFieldStyle, required: Styling for the input field itself. - `backgroundColor` string: Field background color - `borderColor` string, required: Field border color - `borderRadius` string, required: Field border radius in pixels. Range: 0-50 - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Field border style - `borderWidth` string, required: Field border width in pixels - `color` string, required: Field text color - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `fontFamily` string, required: Field font family - `fontSize` string, required: Field font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal': Field font style - `fontWeight` 'bold' | 'normal': Field font weight - `label` FormFieldLabelStyles, required: Styling for field labels. - `color` string, required: Label color - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `placeholder` FormFieldPlaceholderStyles, required: Styling for field placeholders. - `color` string, required: Placeholder color - `textAlign` 'left' | 'center' | 'right': Field text alignment - `textDecoration` 'underline' | 'none': Field text decoration - `link` FormLink, required: Link color settings. - `color` string, required: Link color - `position` 'topLeft' | 'topCenter' | 'topRight' | 'middleLeft' | 'middleCenter' | 'middleRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight': Form position on the page - `textPresets` FormTextPreset[], required: Named text style presets - `id` 'heading_large' | 'heading_medium' | 'heading_small' | 'paragraph' | 'footnote', required: Preset identifier - `name` string: Preset name - `styles` FormTextStyle, required: Styling applied to a text preset. - `color` string, required: Text color - `fontFamily` string, required: Text font family - `fontSize` string, required: Text font size in pixels. Range: 8-96 - `lineHeight` '100%' | '115%' | '125%' | '150%' | '200%', required: Text line height - `steps` FormStep[], required: Form steps, each containing sections - `sections` FormSection[], required: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRow[], required: Rows contained in the section - `columns` FormColumn[], required: Columns contained in the row - `blocks` FormBlock[], required: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string, required: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `subscribedStep` FormStep: A step of a form submitted when creating a form. - `sections` FormSection[], required: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRow[], required: Rows contained in the section - `columns` FormColumn[], required: Columns contained in the row - `blocks` FormBlock[], required: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string, required: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `successStep` FormStep: A step of a form submitted when creating a form. - `sections` FormSection[], required: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRow[], required: Rows contained in the section - `columns` FormColumn[], required: Columns contained in the row - `blocks` FormBlock[], required: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string, required: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `teaser` FormTeaser: Teaser shown before or after the form. - `closeButton` FormTeaserCloseButton: Teaser close button settings. - `isEnabled` boolean: Whether the teaser close button is shown - `isEnabled` boolean: Whether the teaser is enabled - `position` 'topLeft' | 'topCenter' | 'topRight' | 'middleLeft' | 'middleRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight', required: Teaser position on the page - `styleProperties` FormTeaserStyleProperties: Teaser styling. - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels. Range: 0-50 - `color` string: Text color - `desktopStyle` FormResponsiveTeaserStyle, required: Responsive teaser margins. - `marginBottom` string: Bottom margin in pixels - `marginLeft` string: Left margin in pixels - `marginRight` string: Right margin in pixels - `marginTop` string: Top margin in pixels - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal': Font style - `fontWeight` 'bold' | 'normal': Font weight - `mobileStyle` FormResponsiveTeaserStyle, required: Responsive teaser margins. - `marginBottom` string: Bottom margin in pixels - `marginLeft` string: Left margin in pixels - `marginRight` string: Right margin in pixels - `marginTop` string: Top margin in pixels - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `shape` 'rectangle' | 'circle' | 'triangle', required: Teaser shape - `textDecoration` 'underline' | 'none': Text decoration - `text` string, required: Teaser text - `visibility` 'before' | 'after' | 'always', required: When the teaser is shown relative to the form - `unavailablePageStep` FormStep: A step of a form submitted when creating a form. - `sections` FormSection[], required: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRow[], required: Rows contained in the section - `columns` FormColumn[], required: Columns contained in the row - `blocks` FormBlock[], required: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string, required: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `displayType` 'popup' | 'landingPage' | 'embedded' | 'flyout' | 'fullscreen': Form display type - `doubleOptIn` FormDoubleOptIn: Double opt-in configuration. - `confirmationPage` FormDoubleOptInConfirmationPage: Double opt-in confirmation page content. - `autoRedirectText` string: Text shown while the page auto-redirects - `buttonText` string: Confirmation button label - `content` string, required: Confirmation page body content - `isAutoRedirectEnabled` boolean: Whether the page auto-redirects after confirmation - `isButtonVisible` boolean: Whether the confirmation button is shown - `title` string, required: Confirmation page title - `url` string: URL to redirect to after confirmation - `confirmationRedirect` FormDoubleOptInConfirmationRedirect: Double opt-in confirmation redirect settings. - `isEnabled` boolean: Whether confirmation redirect is enabled - `url` string: URL to redirect to after confirmation - `email` FormDoubleOptInEmail: Double opt-in confirmation email content. - `confirmationButton` string, required: Confirmation button label - `content` string, required: Email body content - `headline` string, required: Email headline - `sendersEmail` string: Verified double opt-in sender email - `sendersName` string, required: Sender name shown on the email - `subject` string, required: Email subject line - `isEnabled` boolean: Whether double opt-in is enabled - `name` string: Form name - `recaptcha` FormRecaptchaSettings: reCAPTCHA protection settings. - `isEnabled` boolean: Whether reCAPTCHA protection is enabled - `socialMediaSharing` FormSocialMediaSharing: Social media sharing metadata. - `description` string, required: Shared preview description - `imageID` string: ImageID references an existing image in the Images API. - `title` string, required: Shared preview title - `targeting` FormTargeting: Targeting rules controlling when and to whom a form is shown. - `audience` FormAudience: Subscriber audience targeting. - `type` 'subscribers' | 'notSubscribers': Subscriber audience type. - `cart` FormCartTargeting: Shopping cart targeting rules. Available only for Shopify stores; requests for other platforms are rejected. Each threshold means "at least"; when both are set, both must hold. - `itemCount` integer: Minimum number of items in the cart - `value` integer: Minimum cart value in minor currency units (e.g. 5000 means 50.00). Currency-agnostic - `device` 'desktop' | 'mobile': Device targeting for a form. - `display` FormDisplay: Display trigger configuration controlling when a form appears. - `afterScrollDown` integer: Scroll depth percentage that triggers the form. Range: 0-100 - `afterSeconds` integer: Seconds elapsed on the page before the form appears - `afterViewedPageCount` integer: Number of viewed pages before the form appears - `customTrigger` 'only': Custom trigger mode activating the form - `isExitIntentEnabled` boolean: Whether the form appears on exit intent - `frequency` FormFrequency: Frequency configuration for repeat form displays. - `type` 'second' | 'minute' | 'hour' | 'day': Time unit for the display frequency - `value` integer: Number of time units between repeat displays - `isBackInStock` boolean: Whether targeting is limited to back-in-stock visitors - `location` FormLocationTargeting: Geographic location targeting. - `excludes` FormCountry[]: Countries the form is hidden in - `code` string, required: ISO 3166-1 alpha-2 country code - `name` string, required: Country name - `states` FormState[]: States or regions within the country - `code` string, required: State or region code - `name` string, required: State or region name - `includes` FormCountry[]: Countries the form is shown in - `code` string, required: ISO 3166-1 alpha-2 country code - `name` string, required: Country name - `states` FormState[]: States or regions within the country - `code` string, required: State or region code - `name` string, required: State or region name - `scheduling` FormScheduling: Scheduling window during which a form is active. - `endsAt` string: Scheduling window end timestamp (RFC 3339). Must be later than startsAt. - `startsAt` string: Scheduling window start timestamp (RFC 3339) - `segments` FormSegments: Segment membership targeting. - `excludes` string[]: Segment identifiers the form is hidden for - `includes` string[]: Segment identifiers the form is shown for - `source` FormSourceTargeting: Traffic-source targeting rules. - `excludes` FormSourceType[]: Traffic sources the form is hidden for - `includes` FormSourceType[]: Traffic sources the form is shown for - `url` FormURLTargeting: URL targeting rules. - `excludes` FormURLTarget[]: URLs the form is hidden on - `type` 'exact' | 'contains', required: Match mode for the URL rule - `value` string, required: URL or URL fragment to match - `includes` FormURLTarget[]: URLs the form is shown on - `type` 'exact' | 'contains', required: Match mode for the URL rule - `value` string, required: URL or URL fragment to match - `utm` FormUTMTargeting: UTM parameter targeting. - `includes` FormUTMTarget[]: UTM rules the form is shown for - `type` 'id' | 'source' | 'medium' | 'campaign' | 'term' | 'content', required: UTM parameter the rule matches - `value` string, required: UTM value to match ## Response `200` Updated form - Form: Form resource returned after creation - `abSetupID` string: A/B setup unique identifier the form belongs to (read-only) - `abStatus` 'enabled' | 'draft' | 'disabled': A/B test status of a form. `disabled` is a launched A/B test that is currently paused. - `autoRedirect` FormAutoRedirect: Auto-redirect configuration shown after a successful submission. - `countdownText` string: Text shown during the redirect countdown - `delayMs` integer: Delay before redirecting, in milliseconds. Range: 1000-60000 - `isEnabled` boolean: Whether auto-redirect is enabled - `shouldOpenInNewTab` boolean: Whether the redirect opens in a new tab - `url` string: URL to redirect to after submission - `clickOutside` FormClickOutside: Click-outside-to-close behavior configuration. - `isEnabled` boolean: Whether clicking outside the form closes it - `contactTags` string[]: Tags applied to contacts who submit the form - `content` FormContentResponse: Form content returned in a form response. - `generalSettings` FormGeneralSettingsResponse: General presentation settings returned in a form response. - `backgroundImage` FormBackgroundImageResponse: Background image returned in a form response. - `fit` string: Background image fit - `padding` string: Background image padding in pixels or percent - `position` string: Background image position - `size` string: Background image size in pixels or percent - `url` string: URL to the background image - `body` FormBody: Form body (container) presentation. - `backgroundColor` string: Body background color - `borderColor` string: Body border color - `borderRadius` string, required: Body border radius in pixels - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Body border style - `borderWidth` string, required: Body border width in pixels - `buttonPresets` FormButtonPreset[]: Named button style presets - `id` 'primary_button' | 'secondary_button' | 'tertiary_button', required: Preset identifier - `name` string: Preset name - `styles` FormButtonStyle, required: Styling applied to a button preset. - `backgroundColor` string: Button background color - `borderColor` string: Button border color - `borderRadius` string, required: Button border radius in pixels. Range: 0-50 - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Button border style - `borderWidth` string, required: Button border width in pixels - `color` string, required: Button text color - `fontFamily` string, required: Button font family - `fontSize` string, required: Button font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal', required: Button font style - `fontWeight` 'bold' | 'normal', required: Button font weight - `hoverBackgroundColor` string: Button background color on hover - `hoverBorderColor` string: Button border color on hover - `hoverColor` string: Button text color on hover - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `textAlign` 'left' | 'center' | 'right': Button text alignment - `textDecoration` 'underline' | 'none', required: Button text decoration - `closeButton` FormCloseButton: Close button appearance. - `backgroundColor` string: Close button background color - `color` string, required: Close button color - `isVisible` boolean: Whether the close button is visible - `content` FormContentSettings: Form container dimensions and overlay color. - `color` string, required: Overlay color behind the form - `width` string, required: Form container width in pixels - `fieldStyles` FormFieldStyles: Styling shared across form input fields. - `errorColor` string, required: Validation error text color - `field` FormFieldStyle, required: Styling for the input field itself. - `backgroundColor` string: Field background color - `borderColor` string, required: Field border color - `borderRadius` string, required: Field border radius in pixels. Range: 0-50 - `borderStyle` 'dotted' | 'solid' | 'dashed', required: Field border style - `borderWidth` string, required: Field border width in pixels - `color` string, required: Field text color - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `fontFamily` string, required: Field font family - `fontSize` string, required: Field font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal': Field font style - `fontWeight` 'bold' | 'normal': Field font weight - `label` FormFieldLabelStyles, required: Styling for field labels. - `color` string, required: Label color - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `placeholder` FormFieldPlaceholderStyles, required: Styling for field placeholders. - `color` string, required: Placeholder color - `textAlign` 'left' | 'center' | 'right': Field text alignment - `textDecoration` 'underline' | 'none': Field text decoration - `link` FormLink: Link color settings. - `color` string, required: Link color - `position` string: Form position on the page - `textPresets` FormTextPreset[]: Named text style presets - `id` 'heading_large' | 'heading_medium' | 'heading_small' | 'paragraph' | 'footnote', required: Preset identifier - `name` string: Preset name - `styles` FormTextStyle, required: Styling applied to a text preset. - `color` string, required: Text color - `fontFamily` string, required: Text font family - `fontSize` string, required: Text font size in pixels. Range: 8-96 - `lineHeight` '100%' | '115%' | '125%' | '150%' | '200%', required: Text line height - `steps` FormStepResponse[]: Form steps, each a list of sections - `sections` FormSectionResponse[]: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRowResponse[]: Rows contained in the section - `columns` FormColumnResponse[]: Columns contained in the row - `blocks` FormBlockResponse[]: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `subscribedStep` FormStepResponse: A step of a form returned in a form response. - `sections` FormSectionResponse[]: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRowResponse[]: Rows contained in the section - `columns` FormColumnResponse[]: Columns contained in the row - `blocks` FormBlockResponse[]: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `successStep` FormStepResponse: A step of a form returned in a form response. - `sections` FormSectionResponse[]: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRowResponse[]: Rows contained in the section - `columns` FormColumnResponse[]: Columns contained in the row - `blocks` FormBlockResponse[]: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `teaser` FormTeaser: Teaser shown before or after the form. - `closeButton` FormTeaserCloseButton: Teaser close button settings. - `isEnabled` boolean: Whether the teaser close button is shown - `isEnabled` boolean: Whether the teaser is enabled - `position` 'topLeft' | 'topCenter' | 'topRight' | 'middleLeft' | 'middleRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight', required: Teaser position on the page - `styleProperties` FormTeaserStyleProperties: Teaser styling. - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels. Range: 0-50 - `color` string: Text color - `desktopStyle` FormResponsiveTeaserStyle, required: Responsive teaser margins. - `marginBottom` string: Bottom margin in pixels - `marginLeft` string: Left margin in pixels - `marginRight` string: Right margin in pixels - `marginTop` string: Top margin in pixels - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96 - `fontStyle` 'italic' | 'normal': Font style - `fontWeight` 'bold' | 'normal': Font weight - `mobileStyle` FormResponsiveTeaserStyle, required: Responsive teaser margins. - `marginBottom` string: Bottom margin in pixels - `marginLeft` string: Left margin in pixels - `marginRight` string: Right margin in pixels - `marginTop` string: Top margin in pixels - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `shape` 'rectangle' | 'circle' | 'triangle', required: Teaser shape - `textDecoration` 'underline' | 'none': Text decoration - `text` string, required: Teaser text - `visibility` 'before' | 'after' | 'always', required: When the teaser is shown relative to the form - `unavailablePageStep` FormStepResponse: A step of a form returned in a form response. - `sections` FormSectionResponse[]: Sections contained in the step - `id` string: Section unique identifier (read-only) - `rows` FormRowResponse[]: Rows contained in the section - `columns` FormColumnResponse[]: Columns contained in the row - `blocks` FormBlockResponse[]: Content blocks contained in the column - … - `id` string: Column unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - … - `width` string: Column width in pixels or percent - `id` string: Row unique identifier (read-only) - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `styleProperties` FormStyleProperties: Style properties shared by sections, rows, columns and blocks. - `alignment` 'left' | 'center' | 'right': Horizontal alignment - `backgroundColor` string: Background color - `border` string: CSS border shorthand - `borderRadius` string: Border radius in pixels - `color` string: Primary color - `dividerColor` string: Divider color - `fontFamily` string: Font family - `fontSize` string: Font size in pixels. Range: 8-96, except legal blocks which allow a minimum of 4 - `lineHeight` string: Line height - `opacity` number: Opacity. Range: 0-1 - `paddingBottom` string: Bottom padding in pixels - `paddingLeft` string: Left padding in pixels - `paddingRight` string: Right padding in pixels - `paddingTop` string: Top padding in pixels - `secondaryColor` string: Secondary color - `verticalAlign` 'top' | 'middle' | 'bottom': Vertical alignment - `createdAt` string: Form creation timestamp (read-only) - `disabledAt` string: Form disable timestamp (read-only) - `displayType` 'popup' | 'landingPage' | 'embedded' | 'flyout' | 'fullscreen': Form display type, controlling how the form is presented to visitors. `popup` is a modal centered over the page (highest visibility, best for offers and exit-intent); `flyout` is a compact panel anchored to a corner (non-intrusive, always-on signup); `embedded` renders inline within the host page's content (permanent signup block); `landingPage` is a full standalone page hosted by Omnisend (ad or link driven campaigns); `fullscreen` is a modal that covers the whole viewport (maximum attention, no surrounding page visible). - `doubleOptIn` FormDoubleOptIn: Double opt-in configuration. - `confirmationPage` FormDoubleOptInConfirmationPage: Double opt-in confirmation page content. - `autoRedirectText` string: Text shown while the page auto-redirects - `buttonText` string: Confirmation button label - `content` string, required: Confirmation page body content - `isAutoRedirectEnabled` boolean: Whether the page auto-redirects after confirmation - `isButtonVisible` boolean: Whether the confirmation button is shown - `title` string, required: Confirmation page title - `url` string: URL to redirect to after confirmation - `confirmationRedirect` FormDoubleOptInConfirmationRedirect: Double opt-in confirmation redirect settings. - `isEnabled` boolean: Whether confirmation redirect is enabled - `url` string: URL to redirect to after confirmation - `email` FormDoubleOptInEmail: Double opt-in confirmation email content. - `confirmationButton` string, required: Confirmation button label - `content` string, required: Email body content - `headline` string, required: Email headline - `sendersEmail` string: Verified double opt-in sender email - `sendersName` string, required: Sender name shown on the email - `subject` string, required: Email subject line - `isEnabled` boolean: Whether double opt-in is enabled - `enabledAt` string: Form enable timestamp (read-only) - `id` string: Form unique identifier (read-only) - `launchedAt` string: Form launch timestamp (read-only) - `name` string: Form name - `recaptcha` FormRecaptchaSettings: reCAPTCHA protection settings. - `isEnabled` boolean: Whether reCAPTCHA protection is enabled - `socialMediaSharing` FormSocialMediaSharingResponse: Social media sharing metadata returned in a form response. - `description` string: Shared preview description - `imageUrl` string: URL to the shared preview image - `title` string: Shared preview title - `status` 'enabled' | 'disabled' | 'draft': Form status. - `targeting` FormTargeting: Targeting rules controlling when and to whom a form is shown. - `audience` FormAudience: Subscriber audience targeting. - `type` 'subscribers' | 'notSubscribers': Subscriber audience type. - `cart` FormCartTargeting: Shopping cart targeting rules. Available only for Shopify stores; requests for other platforms are rejected. Each threshold means "at least"; when both are set, both must hold. - `itemCount` integer: Minimum number of items in the cart - `value` integer: Minimum cart value in minor currency units (e.g. 5000 means 50.00). Currency-agnostic - `device` 'desktop' | 'mobile': Device targeting for a form. - `display` FormDisplay: Display trigger configuration controlling when a form appears. - `afterScrollDown` integer: Scroll depth percentage that triggers the form. Range: 0-100 - `afterSeconds` integer: Seconds elapsed on the page before the form appears - `afterViewedPageCount` integer: Number of viewed pages before the form appears - `customTrigger` 'only': Custom trigger mode activating the form - `isExitIntentEnabled` boolean: Whether the form appears on exit intent - `frequency` FormFrequency: Frequency configuration for repeat form displays. - `type` 'second' | 'minute' | 'hour' | 'day': Time unit for the display frequency - `value` integer: Number of time units between repeat displays - `isBackInStock` boolean: Whether targeting is limited to back-in-stock visitors - `location` FormLocationTargeting: Geographic location targeting. - `excludes` FormCountry[]: Countries the form is hidden in - `code` string, required: ISO 3166-1 alpha-2 country code - `name` string, required: Country name - `states` FormState[]: States or regions within the country - `code` string, required: State or region code - `name` string, required: State or region name - `includes` FormCountry[]: Countries the form is shown in - `code` string, required: ISO 3166-1 alpha-2 country code - `name` string, required: Country name - `states` FormState[]: States or regions within the country - `code` string, required: State or region code - `name` string, required: State or region name - `scheduling` FormScheduling: Scheduling window during which a form is active. - `endsAt` string: Scheduling window end timestamp (RFC 3339). Must be later than startsAt. - `startsAt` string: Scheduling window start timestamp (RFC 3339) - `segments` FormSegments: Segment membership targeting. - `excludes` string[]: Segment identifiers the form is hidden for - `includes` string[]: Segment identifiers the form is shown for - `source` FormSourceTargeting: Traffic-source targeting rules. - `excludes` FormSourceType[]: Traffic sources the form is hidden for - `includes` FormSourceType[]: Traffic sources the form is shown for - `url` FormURLTargeting: URL targeting rules. - `excludes` FormURLTarget[]: URLs the form is hidden on - `type` 'exact' | 'contains', required: Match mode for the URL rule - `value` string, required: URL or URL fragment to match - `includes` FormURLTarget[]: URLs the form is shown on - `type` 'exact' | 'contains', required: Match mode for the URL rule - `value` string, required: URL or URL fragment to match - `utm` FormUTMTargeting: UTM parameter targeting. - `includes` FormUTMTarget[]: UTM rules the form is shown for - `type` 'id' | 'source' | 'medium' | 'campaign' | 'term' | 'content', required: UTM parameter the rule matches - `value` string, required: UTM value to match - `updatedAt` string: Form last update timestamp (read-only) ## Other responses - `400`: Request contains invalid or missing fields - `401`: Authentication is missing or invalid - `402`: Feature requires a paid add-on - `403`: Insufficient permissions for this operation - `404`: Form not found - `410`: API version has been retired - `429`: Rate limit exceeded - `500`: Unexpected error occurred --- [API](https://skmtc.dev/omnisend/apis/forms-api.md) - [All operations](https://skmtc.dev/omnisend/apis/forms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/forms-api/revisions/9b53556b2e97?raw)