---
title: "Create a Lead Capture pop-up"
method: POST
path: "/api/v1/lead-capture/forms"
tags: ["Lead Capture"]
---

# Create a Lead Capture pop-up

`POST /api/v1/lead-capture/forms`

## Request

- Base URL: `https://www.useboom.ai`
- URL: `https://www.useboom.ai/api/v1/lead-capture/forms`
- Auth: HTTP bearer

Create a pop-up, PAUSED, optionally from a template. Then add prizes and codes with lead_capture_forms_update, and set it ACTIVE there once lead_capture_forms_get shows no liveIssues. Visitors see nothing until it is ACTIVE and the install tag is on an allowed site.

## Request body

- object
  - `name` string, required: Internal name, unique in the organization. Not shown to visitors.
  - `template` 'bold_coupon' | 'warm_newsletter' | 'midnight' | 'editorial' | 'wheel' | 'cards' | 'plinko' | 'scratch': A finished starting point: look, image, words and game. `bold_coupon`, `warm_newsletter` (email only), `midnight` and `editorial` (a yes/no screen, the code sent by message) have no game; `wheel`, `cards`, `plinko` and `scratch` are games and need prizes before going live.
  - `allowedOrigins` string[]: Every site the pop-up may open on, as bare origins such as `https://www.example.com`. Matching is exact: `https://example.com` does not cover `https://www.example.com`.

## Response `201`

Success

- object
  - `id` string, required
  - `name` string, required
  - `status` 'PAUSED' | 'ACTIVE', required: ACTIVE shows it to visitors on the allowed sites; it is refused, with the reasons, until the pop-up is ready (at least one site, a prize per game, consent text for a phone).
  - `game` string, required: The game, or `none` for a plain form.
  - `allowedOrigins` string[], required
  - `installKey` string, required: Public; identifies the pop-up in the install tag.
  - `updatedAt` string, required: ISO timestamp.
  - `installTag` string, required: The script tag to paste at the end of the page body.
  - `buttonTag` string, required: A button that opens the pop-up when clicked, whatever its trigger; with the trigger set to `click` it is the only way it opens. The install tag must be on the page too.
  - `config` object, required: The full design, copy, fields, trigger, game and prizes. Send any part of it back as `config` to `lead_capture_forms_update`. Text fields are `{ "en": "…", "es": "…", "pt": "…" }`; `en` is required. `flow.order` is `form-first` (details, then the game) or `play-first` (the game, then details to claim the prize; needs a game). If the stored settings could no longer be read, this shows the defaults and `liveIssues` says so; a patch then starts from the defaults.
  - `liveIssues` string[], required: Why it could not go live as it stands, one `field: reason` per line. Empty when it is ready.

## Other responses

- `400`: Validation failed or the request cannot proceed.
- `401`: Missing, malformed, or revoked API key.
- `404`: The resource does not exist in this organization.
- `409`: Conflicts with the current state (duplicates, wrong lifecycle state).
- `422`: The request is well-formed but semantically invalid.
- `429`: Rate limit exceeded — retry after `Retry-After`.
- `500`: Internal server error.
- `503`: Transient error — retry with a narrower request.

## Changes

- **2026-11-03** `7c7a773b12ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/lead-capture/forms/post.md)

---

[API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)