Opt-In Forms API

The Opt-In Forms API provides full CRUD (Create, Read, Update, Delete) operations for managing subscription forms. You can create, list, view, update, and delete opt-in forms programmatically, including their form blocks (text, input fields, and buttons).

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

  • Read Permission: Required for GET endpoints (list, show)
  • Write Permission: Required for POST, PATCH, DELETE endpoints

Opt-In Form Object

The opt-in form object contains the following fields:

Field Type Description
`id` integer The unique identifier of the form
`identifier` string (UUID) A unique UUID for the form, used for embedding
`label` string The internal name of the form (required)
`form_type` string Type of form: `web` or `embed`
`widget_type` string Widget display type (e.g., popup, slide-in, inline)
`enabled` boolean Whether the form is active (default: true)
`allowed_embedding_domains` array List of domains where the form can be embedded
`theme_settings` object Theme customization (colors, typography, layout, effects)
`automation_settings` object Automation config — see Automation Settings below for the full set of supported keys.
`confirmation_email_template_id` integer ID of the confirmation email template used when double opt-in is enabled. Must belong to the same channel.
`welcome_email_template_id` integer ID of the welcome email template sent after a subscriber confirms (if welcome emails are enabled). Must belong to the same channel.
`security_settings` object Security config (honeypot, rate limiting, Turnstile)
`trigger_settings` object Display trigger config (timing, scroll, exit intent)
`widget_settings` object Widget-specific settings
`analytics` object Analytics data (views_count, unique_views_count, submissions_count, conversion_rate)
`is_variant` boolean Whether this form is an A/B test variant
`variant_name` string Name of the variant (if applicable)
`variant_weight` integer Traffic weight for A/B testing (0-100)
`variants_count` integer Number of variants for this form
`opt_in_form_blocks` array Form blocks for the initial view
`opt_in_post_submission_blocks` array Form blocks for the post-submission view
`embed_url` string URL to embed the form via JavaScript
`created_at` datetime When the form was created
`updated_at` datetime When the form was last updated

Automation Settings

The automation_settings object accepts the following keys. All are optional; unspecified keys retain their previous value when updating.

Key Type Description
`tag_list` string Comma-separated list of tags applied to subscribers who submit this form.
`sequence_ids` array<integer> IDs of sequences a confirmed subscriber is enrolled in.
`send_welcome_email` boolean Whether to send a welcome email after the subscriber confirms (uses `welcome_email_template_id`).
`double_opt_in` boolean Whether to require email confirmation before activating the subscriber.
`include_unsubscribe_link_in_confirmation` boolean Whether the confirmation email includes an unsubscribe link in the footer. Defaults to `true`.
`confirmation_redirect_url` string If set, subscribers are redirected to this URL after confirming instead of seeing Broadcast’s confirmation page. Must be `http://` or `https://`. Only applies to opt-in-form-flow confirmations. See Confirmation Pages.

Form Block Object

Each form block contains the following fields:

Field Type Description
`id` integer The unique identifier of the block
`block_type` string Type of block (see Block Types below)
`form_view` string `initial_view` or `post_submission_view`
`position` integer Order of the block in the form
`text_value` string Text content (for `text` block type)
`heading_level` string Heading level (h1-h6) for text blocks
`input_field_label` string Label for input field
`input_field_placeholder` string Placeholder text for input field
`input_field_value_type` string Type of data: `email`, `first_name`, `last_name`, or `name`
`custom_field_key` string Key under which the value is stored on `subscriber.custom_data`. Used by `custom_field` blocks and by `input_field` blocks with `input_field_value_type: “custom”`. Lowercase letters, numbers, and underscores only; must start with a letter.
`field_required` boolean Whether the field is required
`field_validation` string Validation rules for the field
`multiline` boolean When `true`, a `custom_field` block (or `input_field` with `input_field_value_type: “custom”`) renders as a `