API reference · Broadcasts

Send a broadcast

POST/v1/broadcasts1 operation a passSafe to retry with Idempotency-Key

Sends one message to every active pass a search finds, as Send a notification would to each, in the background.

Body

messagestring, up to 256 charactersrequired

What holders see.

filtersobject

Which passes: the same search and filters as List passes, such as { "q": "gold", "appleInstalled": "true" }. Left out or empty, every active pass. An unknown filter is refused, so a typo can't reach everyone.

Answer

202Started

Which passes it reaches is fixed now: passes made later aren't included. Follow it with Get a broadcast.

Errors

Every error has the same shape: see Errors.

Status	Code	When
400	`validation_error`	No message, it's too long, it has a placeholder such as `{{name}}` (messages are sent exactly as written), or a filter isn't valid.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
409	`broadcast_in_progress`	Another broadcast is still sending: one at a time.
422	`no_matching_passes`	No active pass matches.
429	`broadcast_over_allowance`	It would go past this month's operations. `preview` says what's left.

A pass is never sent the same broadcast twice, even if part of it runs again.

Request

curl "https://api.walletpassapi.com/v1/broadcasts" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: weekend-promo" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Double points this weekend",
    "filters": {
      "status": "active",
      "template": "gold-member"
    }
  }'

const res = await fetch("https://api.walletpassapi.com/v1/broadcasts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "weekend-promo",
  },
  body: JSON.stringify({
    "message": "Double points this weekend",
    "filters": {
      "status": "active",
      "template": "gold-member"
    }
  }),
});
const data = await res.json();

import os

import requests

res = requests.post(
    "https://api.walletpassapi.com/v1/broadcasts",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "weekend-promo"},
    json={
        "message": "Double points this weekend",
        "filters": {
            "status": "active",
            "template": "gold-member",
        },
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/broadcasts");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: weekend-promo",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "message" => "Double points this weekend",
        "filters" => [
            "status" => "active",
            "template" => "gold-member",
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

202 Started

{
  "broadcast": {
    "id": "bc_m2x8k4q7w1n9p3r5",
    "message": "Double points this weekend",
    "status": "sending",
    "total": 1200,
    "sent": 0,
    "skipped": 0,
    "failed": 0,
    "lastError": null,
    "filters": {
      "status": "active",
      "template": "gold-member"
    },
    "createdAt": "2026-10-08T19:31:12.000Z",
    "completedAt": null
  }
}