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`
`enabled` boolean Whether the form is active (default: true)
`allowed_embedding_domains` array List of domains where the form can be embedded
`opt_in_form_blocks` array Form blocks for the initial view
`opt_in_post_submission_blocks` array Form blocks for the post-submission view
`created_at` datetime When the form was created
`updated_at` datetime When the form was last updated

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: `text`, `input_field`, or `button`
`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)
`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`
`button_label` string Label for button (default: “Sign Up”)
`custom_css` string Custom CSS styling for the block

List Opt-In Forms

GET /api/v1/opt_in_forms

Retrieve a list of all opt-in forms for the authenticated broadcast channel, ordered alphabetically by label.

Query Parameters

  • filter (optional): Search forms by label
  • page (optional): Page number for pagination
  • limit (optional): Maximum number of forms to return (default: 250)

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/opt_in_forms

Response

{
  "opt_in_forms": [
    {
      "id": 1,
      "identifier": "550e8400-e29b-41d4-a716-446655440000",
      "label": "Newsletter Signup",
      "form_type": "web",
      "enabled": true,
      "allowed_embedding_domains": [],
      "opt_in_form_blocks": [
        {
          "id": 1,
          "block_type": "text",
          "form_view": "initial_view",
          "position": 1,
          "text_value": "Subscribe to our newsletter",
          "input_field_label": null,
          "input_field_placeholder": null,
          "input_field_value_type": null,
          "button_label": null,
          "custom_css": null
        }
      ],
      "opt_in_post_submission_blocks": [],
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "count": 1,
    "from": 1,
    "to": 1,
    "current": 1,
    "total_pages": 1
  }
}

Get Opt-In Form

GET /api/v1/opt_in_forms/:id

Retrieve details of a specific opt-in form including all its blocks.

Request

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/opt_in_forms/123

Response

{
  "id": 123,
  "identifier": "550e8400-e29b-41d4-a716-446655440000",
  "label": "Newsletter Signup",
  "form_type": "web",
  "enabled": true,
  "allowed_embedding_domains": ["example.com", "blog.example.com"],
  "opt_in_form_blocks": [
    {
      "id": 1,
      "block_type": "text",
      "form_view": "initial_view",
      "position": 1,
      "text_value": "Join our newsletter!",
      "input_field_label": null,
      "input_field_placeholder": null,
      "input_field_value_type": null,
      "button_label": null,
      "custom_css": null
    },
    {
      "id": 2,
      "block_type": "input_field",
      "form_view": "initial_view",
      "position": 2,
      "text_value": null,
      "input_field_label": "Email Address",
      "input_field_placeholder": "[email protected]",
      "input_field_value_type": "email",
      "button_label": null,
      "custom_css": null
    },
    {
      "id": 3,
      "block_type": "button",
      "form_view": "initial_view",
      "position": 3,
      "text_value": null,
      "input_field_label": null,
      "input_field_placeholder": null,
      "input_field_value_type": null,
      "button_label": "Subscribe Now",
      "custom_css": null
    }
  ],
  "opt_in_post_submission_blocks": [
    {
      "id": 4,
      "block_type": "text",
      "form_view": "post_submission_view",
      "position": 1,
      "text_value": "Thanks for subscribing!",
      "input_field_label": null,
      "input_field_placeholder": null,
      "input_field_value_type": null,
      "button_label": null,
      "custom_css": null
    }
  ],
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Create Opt-In Form

POST /api/v1/opt_in_forms

Create a new opt-in form with blocks.

Parameters

  • label (required): Internal name of the form
  • form_type (optional): web (default) or embed
  • enabled (optional): Whether the form is active (default: true)
  • allowed_embedding_domains (optional): Array of domains where the form can be embedded
  • opt_in_form_blocks_attributes (optional): Array of form blocks for the initial view

Request

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "opt_in_form": {
      "label": "Newsletter Signup",
      "form_type": "web",
      "enabled": true,
      "allowed_embedding_domains": ["example.com"],
      "opt_in_form_blocks_attributes": [
        {
          "block_type": "text",
          "text_value": "Subscribe to our newsletter!",
          "position": 1
        },
        {
          "block_type": "input_field",
          "input_field_label": "Email",
          "input_field_value_type": "email",
          "input_field_placeholder": "[email protected]",
          "position": 2
        },
        {
          "block_type": "button",
          "button_label": "Sign Up",
          "position": 3
        }
      ]
    }
  }' \
  http://your-domain.com/api/v1/opt_in_forms

Response

{
  "id": 123,
  "identifier": "550e8400-e29b-41d4-a716-446655440000",
  "label": "Newsletter Signup",
  "form_type": "web",
  "enabled": true,
  "allowed_embedding_domains": ["example.com"],
  "opt_in_form_blocks": [
    {
      "id": 1,
      "block_type": "text",
      "form_view": "initial_view",
      "position": 1,
      "text_value": "Subscribe to our newsletter!",
      "input_field_label": null,
      "input_field_placeholder": null,
      "input_field_value_type": null,
      "button_label": null,
      "custom_css": null
    },
    {
      "id": 2,
      "block_type": "input_field",
      "form_view": "initial_view",
      "position": 2,
      "text_value": null,
      "input_field_label": "Email",
      "input_field_placeholder": "[email protected]",
      "input_field_value_type": "email",
      "button_label": null,
      "custom_css": null
    },
    {
      "id": 3,
      "block_type": "button",
      "form_view": "initial_view",
      "position": 3,
      "text_value": null,
      "input_field_label": null,
      "input_field_placeholder": null,
      "input_field_value_type": null,
      "button_label": "Sign Up",
      "custom_css": null
    }
  ],
  "opt_in_post_submission_blocks": [],
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Update Opt-In Form

PATCH /api/v1/opt_in_forms/:id

Update an existing opt-in form.

Parameters

All parameters are optional. Only include the fields you want to update:

  • label: Internal name of the form
  • form_type: web or embed
  • enabled: Whether the form is active
  • allowed_embedding_domains: Array of domains
  • opt_in_form_blocks_attributes: Array of form blocks (include id to update, _destroy: true to delete)

Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "opt_in_form": {
      "label": "Updated Form Name",
      "enabled": false,
      "opt_in_form_blocks_attributes": [
        {
          "id": 1,
          "text_value": "Updated headline text"
        },
        {
          "id": 2,
          "_destroy": true
        }
      ]
    }
  }' \
  http://your-domain.com/api/v1/opt_in_forms/123

Response

Returns the updated opt-in form object.

Delete Opt-In Form

DELETE /api/v1/opt_in_forms/:id

Delete an opt-in form and all its blocks.

Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://your-domain.com/api/v1/opt_in_forms/123

Response

{
  "message": "Opt-in form deleted successfully"
}

Error Responses

If the request is invalid, the response will include an appropriate HTTP status code and error message:

401 Unauthorized

{
  "error": "Unauthorized"
}

This error occurs when: - No authorization header is provided - The token is invalid or expired - The token doesn’t have the required permissions

404 Not Found

{
  "error": "Opt-in form not found"
}

This error occurs when: - The form ID doesn’t exist - The form belongs to a different broadcast channel

422 Unprocessable Entity

{
  "error": "Label can't be blank"
}

This error occurs when: - Required fields are missing - Validation fails for any reason

Usage Example: Creating a Complete Form

Here’s an example of creating a complete opt-in form with all block types:

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "opt_in_form": {
      "label": "Lead Capture Form",
      "form_type": "embed",
      "enabled": true,
      "allowed_embedding_domains": ["example.com", "blog.example.com"],
      "opt_in_form_blocks_attributes": [
        {
          "block_type": "text",
          "text_value": "Get our weekly newsletter!",
          "position": 1
        },
        {
          "block_type": "input_field",
          "input_field_label": "First Name",
          "input_field_value_type": "first_name",
          "input_field_placeholder": "John",
          "position": 2
        },
        {
          "block_type": "input_field",
          "input_field_label": "Email Address",
          "input_field_value_type": "email",
          "input_field_placeholder": "[email protected]",
          "position": 3
        },
        {
          "block_type": "button",
          "button_label": "Subscribe",
          "position": 4
        }
      ]
    }
  }' \
  http://your-domain.com/api/v1/opt_in_forms