Poplause Events API

Send your real activity to Poplause and it shows up as a beautiful, auto-themed social-proof notification on your site. One JSON POST per event, no SDK required. Server-side calls authenticate with a secret key and land verified; browser calls use your public site ID.

Most people never need this page: connect a tool like Stripe or Shopify on a site's Setup tab and events flow automatically. Use this API when you want full control or you are sending events from your own code.

Authentication

Poplause uses two credentials, the same split you know from Stripe or Segment:

Public site ID– ships in your install snippet, so it is safe in browser code. Pass it in the site field of /api/trackcalls. Browser events are marked unverified.

Secret key (pl_live_…) – authenticates trusted server calls to /api/ingest via anAuthorization: Bearer header. The key identifies the site, so you do not send a sitefield, and those events land verified. Keep it server-side only - never ship it to the browser or commit it to git. Rotate it any time from the site's Setup tab.

Find both in the dashboard: the site ID is the slug in the URL; the secret key lives under Setup → Send your real events.

Send an event

POST /api/track is the everyday endpoint, callable straight from the browser. Events sent here are marked unverified (they came from a page, not a trusted server).

POST https://poplause.com/api/track

curl -X POST https://poplause.com/api/track \
  -H "Content-Type: application/json" \
  -d '{
    "site": "YOUR_SITE_ID",
    "type": "purchase",
    "name": "Ada Lovelace",
    "location": "London",
    "product": "The Everyday Tee",
    "url": "/products/tee"
  }'

Server-side ingest

POST /api/ingest is for trusted, server-to-server calls. Authenticate with your secret key in an Authorization: Bearer header - the key identifies the site, so there is no site field. Events land marked verified, which earns a subtle badge. Call it from your backend when a genuine order or signup happens.

POST https://poplause.com/api/ingest

curl -X POST https://poplause.com/api/ingest \
  -H "Authorization: Bearer pl_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "name": "Grace Hopper",
    "location": "Brooklyn, NY",
    "product": "Annual License"
  }'

Browser helper

The install snippet exposes a global poplause() helper, so you can fire events without writing fetch calls. It posts to /api/track for you and fills in the site ID from the script tag.

<!-- 1. The install snippet you already added to your site -->
<script src="https://poplause.com/t.js" data-site="YOUR_SITE_ID" defer></script>

<!-- 2. Fire an event from anywhere on your page -->
<script>
  window.poplause = window.poplause || function(){(poplause.q=poplause.q||[]).push(arguments)}

  poplause("track", {
    type: "signup",
    name: "Aiko Tanaka",
    location: "Seattle, WA",
  })
</script>

Event fields

Every field except type is optional. Send whatever you have; Poplause composes a clean notification from it and skips anything missing.

Event types

The type field picks the notification style and which fields matter.

Responses & errors

A successful call returns 200 with the stored event ID:

{ "ok": true, "id": "evt_a1b2c3" }

Errors return the matching status with a short message:

Management API

The endpoints above send events. The Management API controls the whole site - customization and full event CRUD - so a script or an agent can manage Poplause without the dashboard. It lives under /api/v1 and uses the same secret key in anAuthorization: Bearer header. The key scopes every call to its one site, so you never pass a site field or an id in the path.

Example - switch position and turn on the widget, then generate warm-up events:

# customize the widget
curl -X PATCH https://poplause.com/api/v1/site \
  -H "Authorization: Bearer pl_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "theme": { "position": "bottom-right", "style": "card" } }'

# generate 12 warm-up events
curl -X POST https://poplause.com/api/v1/events/generate \
  -H "Authorization: Bearer pl_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "count": 12 }'

# later, once real events flow, clear the warm-up ones
curl -X DELETE "https://poplause.com/api/v1/events?simulated=1" \
  -H "Authorization: Bearer pl_live_…"

Note: purchase and signup events require aname- nameless person events are rejected so the widget never shows a generic "Someone".

Agents & MCP

Managing Poplause through an AI agent (Claude Code, Cursor, Claude Desktop)? Thepoplause-mcp server wraps the Management API as MCP tools, so your agent can customize the widget and add, edit, generate or clear events conversationally - no dashboard needed.

Add it to your MCP client config, with the site's secret key:

{
  "mcpServers": {
    "poplause": {
      "command": "npx",
      "args": ["-y", "poplause-mcp"],
      "env": {
        "POPLAUSE_API_KEY": "pl_live_…",
        "POPLAUSE_BASE_URL": "https://poplause.com"
      }
    }
  }
}

Tools exposed:

No-code integrations

Not a developer? You do not need this API. Poplause has native connections for Stripe, Shopify, WooCommerce, PayPal, Typeform, Calendly, Mailchimp and more, plus a universal webhook that maps the fields above automatically. Connect them on the Integrations tab in your dashboard, no code and no secrets to paste.