Retrieve a notification

Returns the notification object - the single source of truth for broadcast state: lifecycle status (queued/scheduled/processing/completed/partial/failed/cancelled), aggregate per-channel stats, and the lifecycle timestamps (schedule_at, sent_at, completed_at).

Need per-recipient granularity (“did customer X get it on which device”)? That’s GET /v1/notifications/{id}/deliveries - an unbounded row collection that cannot live inline on this DTO.

Polling this endpoint is fine for short-lived broadcasts; for high-volume monitoring prefer the notification.delivery_updated webhook. The DTO always shows the unrendered template - per-recipient rendered text is not retrievable.

Scope: notifications:read.

GET /v1/notifications/{id}

Retrieve a notification

cURL

curl --request GET \
  --url https://api.vexioncards.one/v1/notifications/{id} \
  --header 'Authorization: Bearer <token>'

200

Completed broadcast

{
  "id": "ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ",
  "object": "notification",
  "title": {
    "en": "Summer special menu"
  },
  "body": {
    "en": "Try the new lime lemonade for 2.50 EUR."
  },
  "audience": {
    "card_ids": [
      "crd_sophcrprtvpmmnwxah2lomnkee"
    ]
  },
  "status": "completed",
  "schedule_at": null,
  "sent_at": 1782134401,
  "stats": {
    "total": 121,
    "audience_resolved_count": 121,
    "apple_wallet": {
      "total": 98,
      "delivered": 96,
      "failed": 2
    },
    "google_wallet": {
      "total": 23,
      "delivered": 22,
      "failed": 1
    },
    "delivered": 118,
    "failed": 3
  },
  "created_at": 1782134400,
  "completed_at": 1782134522,
  "request_id": "req_01J9P0G7K9C0RYHXJ2K7A4N5MZ"
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Path Parameters

id · string · required

Notification identifier (ntf_ prefix).

Pattern: ^ntf_[A-Za-z0-9]+$

Response

200

application/json

Notification.

A broadcast push notification. Created via POST /v1/notifications, delivered asynchronously to wallet passes (Apple Wallet + Google Wallet). The stored DTO always shows the UNRENDERED template - per-recipient rendered text is not retrievable after the fact.

id · string · required

Notification identifier. Opaque, ntf_ prefix. Immutable.

Pattern: ^ntf_[A-Za-z0-9]+$

Example:

"ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ"

object · string · required

Resource type discriminator. Always 'notification'.

Allowed value: "notification"

Example:

"notification"

title · object · required

Localized title keyed by language code (en, sk, cs, de). At least one locale required. Per-locale value is plain text, 1-60 characters (Apple Wallet's lock-screen banner truncates around 60). Template variables are supported. Card-mechanics variables ({{card.balance}}, {{stamps_remaining}}, ...) require a card-scoped audience (card_ids).

Show child attributes

Example:

{ "en": "Summer special menu" }

body · object · required

Localized body keyed by language code (en, sk, cs, de). At least one locale required. Per-locale value is plain text, 1-240 characters (worst-case room after banner chrome on Apple + Google). Template variables are supported. Card-mechanics variables ({{card.balance}}, {{stamps_remaining}}, ...) require a card-scoped audience (card_ids).

Show child attributes

Example:

{
  "en": "Try the new lime lemonade for 2.50 EUR."
}

status · enum<string> · required

Broadcast lifecycle:

• queued - accepted, fan-out imminent
• scheduled - accepted with a future schedule_at; cancellable until it fires
• processing - worker batches draining
• completed - every per-recipient attempt finished (provider ack'd or retries exhausted; does NOT mean the human saw it)
• partial - finished with failure rate above the warning threshold (~5%)
• failed - catastrophic failure before deliveries (rare; safe to retry with a fresh Idempotency-Key). Reserved: NOT emitted by v1 today (see note below).
• cancelled - cancelled while queued/scheduled

failed is declared but NOT emitted by v1 today. status is DERIVED per read from four raw signals (schedule flag + fire time, fan-out start, drain completion, delivery counters); nothing records a crash that happened before any delivery was attempted, so no code path can produce failed. GET /v1/notifications?status=failed is accepted and returns an empty page rather than an error, so branching over the full enum stays safe. The other six are all live, including cancelled, which is backed by a real cancelledAt timestamp set by DELETE /v1/notifications/{id} and takes precedence over every other signal.

Available options: queued, scheduled, processing, completed, partial, failed, cancelled

Example:

"completed"

stats · object · required

Aggregate delivery counters, updated as the asynchronous fan-out drains (queue → worker batches → per-device dispatch). Starts at zero on accept. For per-recipient rows, use GET /v1/notifications/{id}/deliveries.

Show child attributes

Example:

{
  "total": 121,
  "audience_resolved_count": 121,
  "apple_wallet": { "total": 98, "delivered": 96, "failed": 2 },
  "google_wallet": { "total": 23, "delivered": 22, "failed": 1 },
  "delivered": 118,
  "failed": 3
}

created_at · integer · required

Unix seconds. Time the broadcast was accepted.

Example:

1782134400

audience · object | null

The audience filter this broadcast was sent with. Null/empty = broadcast to all active customers.

Show child attributes

Example:

{
  "card_ids": ["crd_sophcrprtvpmmnwxah2lomnkee"]
}

schedule_at · integer | null

Unix seconds when a scheduled broadcast fires. Null for immediate sends. While in the future, the broadcast is normally status: "scheduled" and cancellable via DELETE. EXCEPTION: if the audience resolved to zero recipients at accept time there is nothing to deliver now or later, so the broadcast is accepted as already finished - status is completed with every counter at 0 and audience_resolved_count: 0, it never appears under ?status=scheduled, and DELETE returns 409 broadcast_not_cancellable even though this value is still in the future. Poll on status, not on schedule_at.

Example:

null

sent_at · integer | null

Unix seconds when fan-out started - set on EVERY send (immediate and scheduled). Null only before dispatch.

Example:

1782134401

completed_at · integer | null

Unix seconds. Populated when status reaches completed, partial, or failed. Null while queued/processing.

Example:

1782134522

request_id · string

The request id of the request that ACCEPTED this broadcast. Include it in support requests: it identifies the exchange where the fan-out actually happened. On an idempotent replay (a repeat call with the same Idempotency-Key, answered with Idempotent-Replayed: true) this deliberately differs from the Vexion-Request-Id response header: the body keeps the original accept id, while the header carries the id of the replay exchange you are holding.

Example:

"req_01J9P0G7K9C0RYHXJ2K7A4N5MZ"