---
title: "Create saved popup"
method: POST
path: "/popups"
tags: ["Widgets"]
---

# Create saved popup

`POST /popups`

Creates a saved on-site signup popup and returns the one-line script tag that deploys it. The popup is published by default, so the script is live as soon as it is added to the site. Trigger, targeting, audience, and duplicate handling stay server-side, so the deployed script carries no API key.

Omit `listIds` to capture into every list, matching the dashboard default.

## Request body

- object
  - `name` string, required
  - `template` 'newsletter-modal' | 'discount-offer' | 'countdown-launch' | 'minimal-slide-in' | 'exit-lead-magnet' | 'live-demo' | 'launch-modal' | 'paper-digest' | 'stark-takeover' | 'top-bar' | 'announcement-bar' | 'fullscreen-welcome' — Starting design for the popup's blocks and theme.
  - `status` 'draft' | 'published'
  - `listIds` string[] — Lists every signup is added to. Omit or pass an empty array to capture into every list.
  - `tagIds` string[]
  - `duplicateStrategy` 'skip' | 'merge' | 'overwrite'
  - `headline` string
  - `description` string
  - `buttonText` string
  - `successMessage` string
  - `redirectUrl` string, uri
  - `presentation` 'modal' | 'slide-in' | 'floating-bar' | 'fullscreen'
  - `placement` 'center' | 'left' | 'right' | 'top' | 'bottom'
  - `trigger` SavedPopupTrigger — When the popup opens. Merged key by key into the popup's current trigger.
    - `type` 'delay' | 'scroll' | 'exit-intent' | 'click' | 'manual'
    - `delaySeconds` integer — Used when type is delay.
    - `scrollPercent` integer — Used when type is scroll.
    - `clickSelector` string — CSS selector of the element that opens the popup. Required when type is click.
  - `targeting` SavedPopupTargeting — Where the popup may show. Empty arrays mean no restriction. Merged key by key.
    - `domains` string[]
    - `paths` string[]
    - `excludedPaths` string[]
    - `device` 'all' | 'desktop' | 'mobile'
  - `schedule` SavedPopupSchedule — Optional run window. Use null on either key to clear it. Merged key by key.
    - `startsAt` string, date-time, nullable
    - `endsAt` string, date-time, nullable — Must be later than startsAt.
  - `frequency` SavedPopupFrequency — How often one visitor sees the popup. Merged key by key.
    - `maxDisplays` integer
    - `windowDays` integer
  - `visual` SavedPopupVisual — Media panel and urgency treatment. Merged key by key.
    - `style` 'none' | 'accent' | 'header' | 'rail' | 'image' | 'countdown'
    - `placement` 'top' | 'left' | 'center' | 'right'
    - `imageUrl` string, uri, nullable
    - `imageAlt` string
    - `countdownMinutes` integer, nullable
  - `theme` object — Optional visual theme overrides (accentColor, backgroundColor, textColor, mutedTextColor, cardColor, borderColor as "#rrggbb", borderRadius 0-32, headingFontFamily, bodyFontFamily, density).
  - `blocks` object[] — Complete replacement for the popup's content blocks. The popup must keep exactly one required email field and one submit button.

## Response `200`

Popup created

- object
  - `success` boolean
  - `popup` SavedPopup — A saved on-site signup popup.
    - `id` string
    - `name` string
    - `status` 'draft' | 'published'
    - `content` object — Complete popup content - template, presentation, placement, theme, settings, trigger, targeting, schedule, frequency, visual, and blocks. Present on detail reads; omitted when listing unless `includeContent=true`.
    - `viewCount` integer — Times the popup was shown to a visitor.
    - `startCount` integer — Times a visitor began filling the popup in. Always between viewCount and conversionCount.
    - `conversionCount` integer — Times a visitor submitted the popup and became a subscriber.
    - `stats` SavedPopupStats — The popup funnel - shown, started, submitted - with rates derived from the raw counters. A rate is null rather than 0 when its denominator is zero, so "nobody has seen it yet" never reads as "nobody converted".
      - `views` integer
      - `starts` integer
      - `conversions` integer
      - `startRate` number, nullable — starts / views, 0-1. Null when the popup has no views.
      - `conversionRate` number, nullable — conversions / views, 0-1. Null when the popup has no views.
      - `completionRate` number, nullable — conversions / starts, 0-1. Null when nobody has started it.
    - `publishedAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `url` string, uri — Dashboard URL for this popup.
  - `embed` SavedPopupEmbed — Deployment snippets for a published popup. Present only when the popup is published; they contain no API key.
    - `scriptUrl` string, uri
    - `javascript` string
    - `react` string
    - `wordpress` string
    - `shopify` string
    - `supportedPlatforms` string[]
  - `message` string

## Other responses

- `400` — Invalid template, status, audience, redirect URL, or popup content
- `401` — Unauthorized
- `403` — API key is missing widgets:write
- `500` — Failed to create popup

---

[API](https://skmtc.net/sequenzy/apis/sequenzy-api.md) · [All operations](https://skmtc.net/sequenzy/apis/sequenzy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sequenzy/sequenzy-api/revisions/16ad4f8e3d97/schema)