Popups API

Website popups, with targeting and A/B conversion counts.

Module code popups · 4 actions · 2 data models · 2 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: popups (everything), popups:read (read only) or popups:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

popups.delete

Delete a popup — Deletes the popup and its anonymous counts.

Needs popups:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/popups.delete

Input

Events it publishes: popups.deleted

What it writes: popup (delete) — Deletes the popup; popup_event (delete) — Deletes its counts

curl -X POST https://app.getera.io/api/v1/popups/actions/delete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"ID_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "popups.deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.popups.delete({
  id: "ID_ID"
})

era popups delete \
  --id "ID_ID"

{
  "name": "era__popups__delete",
  "arguments": {
    "id": "ID_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold popups:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 429 slow down

popups.save

Create or edit a popup — Saves a popup shown to visitors on your website, with its targeting and A/B content.

Needs popups:manage · changes data

• Canonical address: POST /api/v1/actions/popups.save

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: popups.saved

What it writes: popup (upsert) — Saves the popup as a new revision

curl -X POST https://app.getera.io/api/v1/popups/actions/save \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name","siteId":"SITE_ID","config":{}}'

{
  "ok": true,
  "result": "…",
  "events": [
    "popups.saved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.popups.save({
  name: "Name",
  siteId: "SITE_ID",
  config: {}
})

era popups save --data '{"name":"Name","siteId":"SITE_ID","config":{}}'

{
  "name": "era__popups__save",
  "arguments": {
    "name": "Name",
    "siteId": "SITE_ID",
    "config": {}
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold popups:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 popup_invalid · 429 slow down

popups.submit

Send a popup form — Creates a lead through the form engine and counts the successful send for the A/B test.

Needs popups:write · reaches outside (sends, publishes or charges) · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/popups.submit

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: popup_event (insert) — A successful form send

Errors: 401 no or expired credential · 403 the credential does not hold popups:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 popup_invalid · 429 slow down

popups.track

Count a popup interaction — Records an anonymous view or click, once.

Needs popups:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/popups.track

Input

Preconditions

The action is refused with 409 and one of these codes:

What it writes: popup_event (insert) — One interaction

Errors: 401 no or expired credential · 403 the credential does not hold popups:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 popup_invalid · 429 slow down

Data models

PopupEvent

Table popup_event · Resource popup_events

• GET /api/v1/popup_events
• GET /api/v1/popup_events/{id}

Primary key: id

Unique: popup_id, revision, impression_id, kind

Popup

Table popup · Resource popups

• GET /api/v1/popups
• GET /api/v1/popups/{id}

Primary key: id

Checks:

• CHECK (((ends_at IS NULL) OR (starts_at IS NULL) OR (ends_at > starts_at)))

Events

Workflows and webhooks react to these events.