Ads Placement API Reference

Everything below is the live production contract. One endpoint, five body-selected actions.

Base URL

Onboarding

Partner accounts are provisioned manually — email AL@SavingsSites.com. You receive, exactly once:

Your account is configured with three negotiated settings: ads enabled (the gate for this API), a max payout weight ceiling, and a monthly send cap that bounds your post-paid exposure. Sandbox credentials are available on request for integration testing.

Authentication & request signing

Every request carries three headers:

The signing payload is the timestamp and the exact raw request body joined by a single newline character:

payload   = timestamp + "\n" + rawBody
signature = "sha256=" + hex( HMAC_SHA256( signing_secret, payload ) )

Optionally send Idempotency-Key (up to 128 characters) on create requests. Replays with the same key return the original deal_id with "duplicate": true instead of creating a second placement.

See Code Examples for working signing code in Node, Python, and cURL.

Actions

The JSON body always includes an action field. Successful responses are 200 with "ok": true; failures return "ok": false plus an error code (see Error codes).

create Add a placement

{
  "action": "create",
  "deal": { … placement object, see below … }
}

Response:

{ "ok": true, "deal_id": "p_yourpartnerid_summer_promo", "ad": { …stored row… } }

The server namespaces your deal_id: whatever suffix you supply (lowercased, a-z 0-9 _ -, max 48 chars) is stored as p_<partner_id>_<suffix>. If you omit it, a timestamp-based suffix is generated. Use the returned deal_id in all later calls. Duplicate ids return deal_id_exists.

update Modify a placement

{
  "action": "update",
  "deal_id": "p_yourpartnerid_summer_promo",
  "deal": { "payout_weight": 80, "creative": { "copy": "New copy…" } }
}

A partial patch: supplied fields are merged onto the stored row (creative merges field-by-field; targeting replaces wholesale), then the merged object is re-validated end to end. Response mirrors create.

delete Retract a placement

{ "action": "delete", "deal_id": "p_yourpartnerid_summer_promo" }

Response: { "ok": true, "deal_id": "…", "deleted": true }. The placement leaves rotation within about 60 seconds (server catalog cache TTL).

list Live placements + caps snapshot

{ "action": "list" }

{
  "ok": true,
  "partner_id": "yourpartnerid",
  "count": 12,
  "max_ads": 100,
  "monthly_send_cap": 250000,
  "month_to_date_sends": 48210,
  "ads": [ { …placement rows… } ]
}

ledger Per-placement performance (billing source)

{ "action": "ledger" }

{
  "ok": true,
  "partner_id": "yourpartnerid",
  "month": "2026-07",
  "month_to_date_sends": 48210,
  "monthly_send_cap": 250000,
  "deals": [
    {
      "deal_id": "p_yourpartnerid_summer_promo",
      "expires_at": 1722470400000,
      "totals":        { "sends": 9120, "views": 6011, "clicks": 402 },
      "last_7_days":   { "sends": 2210, "views": 1544, "clicks": 118 },
      "month_to_date": { "sends": 9120, "views": 6011, "clicks": 402 }
    }
  ]
}

Sends are metered server-side at append time and are authoritative. Views and clicks are reported best-effort by recipient clients — treat them as engagement signal, not an invoice line.

Placement object

{
  "deal_id": "summer_promo",
  "expires_at": 1722470400000,
  "payout_weight": 50,
  "price_usd": 9.99,
  "main_category": "home-services",
  "sub_category": "security",
  "creative": {
    "copy": "20% off first-year monitoring for new movers.",
    "url": "https://advertiser.example.com/offer",
    "audio_url": "https://cdn.example.com/spot.webm",
    "audio_title": "New mover special — 30 second spot",
    "audio_duration_ms": 30000
  },
  "snap_badge": { "shape": "pill", "color": "#1E1E1E", "label": "AD" },
  "targeting": { … see targeting reference … }
}

All creative text passes a family-safe content filter (copy, audio_title, badge label). Rejected content returns content_not_allowed plus the offending field.

Targeting reference

"targeting": {
  "target_mode": "both",
  "zips": ["07001", "07002"],
  "geo_radius": [ { "zip": "07104", "miles": 25, "branch": "both" } ],
  "resident_filters": {
    "genders": ["female"],
    "age_groups": ["under_36", "36_60"]
  },
  "business_filters": {
    "org_sizes": ["solo", "2_10"],
    "primary_roles": ["founder_owner"],
    "target_markets": ["b2b"],
    "business_categories": ["real_estate", "home_services"]
  }
}

Business category slugs: software_technology, it_services_cybersecurity, marketing_advertising, media_creative_design, legal_compliance, accounting_tax, consulting_business_services, architecture_engineering, real_estate, construction_trades, manufacturing, logistics_supply_chain, agriculture_natural_resources, energy_utilities, automotive, home_services, retail_ecommerce, food_beverage, hospitality_travel, fitness_recreation, finance_insurance, healthcare_medical, pharma_biotech, education_training, nonprofit, government_public_sector, associations_membership, telecommunications, other.

Filters combine with AND: a recipient must match the branch, the geo set (explicit ZIPs ∪ radius ZIPs), and every demographic filter you set. Unset filters match everyone. Targeting is evaluated entirely on our servers against the recipient's self-declared profile — no recipient data is ever returned to you.

Delivery & selection

• New and updated placements enter rotation within about 60 seconds (catalog cache TTL).
• When a Blast is delivered, all live placements matching the recipient compete; the highest payout_weight wins the slot, with random tie-breaking among equal weights.
• The ad is appended after the message body — clearly separated and badge-labeled. Audio spots render as a "Sponsored — audio from advertiser" block with a Listen player.
• If nothing matches, a house ad runs — you're never charged for unmatched traffic.

Billing

• Post-paid. No prepay, no per-call charge. Invoicing settles from the server-metered sends in your ledger.
• Monthly send cap. When your month-to-date sends reach your cap, all your placements pause automatically until the first of the next month (UTC). list and ledger both show cap and month-to-date so you can monitor pacing.

Limits

Error codes