> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Popup

> Create an on-site signup popup and get its embed script

Create a saved popup and get 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

<ParamField body="name" type="string" required>
  Internal popup name.
</ParamField>

<ParamField body="template" type="string">
  Starting design: `newsletter-modal`, `discount-offer`, `countdown-launch`,
  `minimal-slide-in`, `exit-lead-magnet`, `live-demo`, `launch-modal`,
  `paper-digest`, `stark-takeover`, `top-bar`, `announcement-bar`, or
  `fullscreen-welcome`. Defaults to `newsletter-modal`.
</ParamField>

<ParamField body="status" type="string">
  `draft` or `published`. Defaults to `published`.
</ParamField>

<ParamField body="listIds" type="string[]">
  Lists every signup joins. Omit or pass an empty array to capture into every
  list.
</ParamField>

<ParamField body="tagIds" type="string[]">
  Existing tag IDs to apply.
</ParamField>

<ParamField body="duplicateStrategy" type="string">
  `skip`, `merge`, or `overwrite`. Defaults to `skip`.
</ParamField>

<ParamField body="headline" type="string">
  Text for the popup's first heading block.
</ParamField>

<ParamField body="description" type="string">
  Text for the popup's first paragraph block.
</ParamField>

<ParamField body="buttonText" type="string">
  Submit button label.
</ParamField>

<ParamField body="successMessage" type="string">
  Confirmation shown when `redirectUrl` is omitted.
</ParamField>

<ParamField body="redirectUrl" type="string">
  Optional HTTP or HTTPS success redirect.
</ParamField>

<ParamField body="presentation" type="string">
  `modal`, `slide-in`, `floating-bar`, or `fullscreen`.
</ParamField>

<ParamField body="placement" type="string">
  `center`, `left`, `right`, `top`, or `bottom`.
</ParamField>

<ParamField body="trigger" type="object">
  When the popup opens: `{ "type": "delay" | "scroll" | "exit-intent" | "click"   | "manual", "delaySeconds": 0-3600, "scrollPercent": 1-100, "clickSelector":
      "#join" }`. A `click` trigger requires a `clickSelector`.
</ParamField>

<ParamField body="targeting" type="object">
  Where it may show: `{ "domains": [], "paths": [], "excludedPaths": [],
      "device": "all" | "desktop" | "mobile" }`. Empty arrays mean no restriction.
</ParamField>

<ParamField body="schedule" type="object">
  Optional run window: `{ "startsAt": "2026-09-01T00:00:00Z", "endsAt":
      "2026-09-08T00:00:00Z" }`. `endsAt` must be later than `startsAt`.
</ParamField>

<ParamField body="frequency" type="object">
  How often one visitor sees it: `{ "maxDisplays": 1-100, "windowDays": 1-365 }`.
</ParamField>

<ParamField body="visual" type="object">
  Media panel and urgency treatment: `{ "style": "none" | "accent" | "header" |
      "rail" | "image" | "countdown", "placement": "top" | "left" | "center" |
      "right", "imageUrl": "https://...", "imageAlt": "...", "countdownMinutes":
      1-10080 }`.
</ParamField>

<ParamField body="theme" type="object">
  Visual theme overrides: `accentColor`, `backgroundColor`, `textColor`,
  `mutedTextColor`, `cardColor`, `borderColor` (all `#rrggbb`), `borderRadius`
  (0-32), `headingFontFamily`, `bodyFontFamily`, `density`.
</ParamField>

<ParamField body="blocks" type="object[]">
  Complete replacement for the popup's content blocks. The popup must keep
  exactly one required email field and one submit button.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/popups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome offer",
    "template": "discount-offer",
    "listIds": ["list_123"],
    "headline": "Take 10% off your first order",
    "trigger": { "type": "exit-intent" }
  }'
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "popup": {
      "id": "pop_123",
      "name": "Welcome offer",
      "status": "published",
      "viewCount": 0,
      "conversionCount": 0,
      "publishedAt": "2026-08-10T09:00:00.000Z"
    },
    "embed": {
      "scriptUrl": "https://sequenzy.com/embed/popups/pop_123?v=capture-runtime-20260716-14",
      "javascript": "<script async src=\"https://sequenzy.com/embed/popups/pop_123?v=capture-runtime-20260716-14\"></script>",
      "supportedPlatforms": ["HTML", "React", "Next.js", "WordPress", "Shopify"]
    },
    "message": "Popup created and published. Add the embed script to the site and the popup starts showing under its trigger and targeting rules."
  }
  ```

  ```json 400 theme={null}
  { "error": "Every listId must belong to the selected company." }
  ```

  ```json 401 theme={null}
  {
    "error": "Missing API key. Provide via x-api-key header or Authorization: Bearer <key>"
  }
  ```

  ```json 403 theme={null}
  { "error": "API key is missing required scope: widgets:write" }
  ```

  ```json 500 theme={null}
  { "error": "Failed to create popup." }
  ```
</ResponseExample>