pushService API Reference
Pass your API key in X-Api-Key. All request and response bodies are JSON.
Base URL: https://push.vinficient.com
- Every request must include the header
X-Api-Key: psk_your_api_key_here. - API keys are scoped to a single tenant. A key cannot read or write another tenant's subscribers.
- Keys are shown once at creation in the dashboard — store them securely. Lost keys must be revoked and replaced.
- Rate limit: 60 send requests per minute per API key. Exceeding this returns
429 Too Many Requests. - Service-to-service callers using
PUSH_SERVICE_KEYbypass credit checks but still require a valid key.
Deliver a push notification to all active devices enrolled under the given email address within your tenant. Each successful delivery debits 1 credit. Failed deliveries (expired subscriptions, 410 Gone) are not charged.
// Required headers X-Api-Key: psk_your_api_key_here Content-Type: application/json // Request body { "email": "[email protected]", // required — subscriber email (hashed server-side, not stored plaintext) "title": "Your table is ready", // required — notification headline "body": "Head to the host stand — your party of 4 is up.", // required "url": "https://your-site.com/reservation/abc123" // optional — tap target URL }
{
"sent": 2, // subscriptions notified (e.g. iPhone + laptop)
"failed": 0, // expired/gone subscriptions (not charged)
"credits": 9998 // credits remaining after this send
}
Stores a browser PushSubscription object linked to a subscriber email.
This endpoint is called automatically by the tenant's PWA after the user grants
notification permission — your backend does not need to call it. Documented here
for manual integration or custom PWA builds.
// The PWA calls this automatically after permission is granted. // Manual integration passes the browser's PushSubscription object. { "email": "[email protected]", "subscription": { /* browser PushSubscription JSON — endpoint, keys.p256dh, keys.auth */ } } // Response — 201 Created { "ok": true }
Deactivates all push subscriptions for the given email within your tenant. Useful when a user opts out of notifications in your app before the browser subscription naturally expires. Expired/gone subscriptions are cleaned up automatically on send — manual unsubscription is optional.
{
"email": "[email protected]"
}
// Response — 200 OK
{ "removed": 2 } // number of subscription rows deactivated
All errors return JSON with an error string field describing the problem.
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or malformed required fields (email, title, body). |
| 401 | Missing or invalid X-Api-Key header. |
| 402 | Insufficient credits — tenant credit balance is zero. Top up via the dashboard or ssoBilling. |
| 404 | No active subscriptions found for the given email within this tenant. Either the user never subscribed, or all subscriptions have expired. |
| 429 | Rate limit exceeded — more than 60 requests/minute for this API key. Back off and retry after 1 minute. |
| 5xx | Server error. Safe to retry with exponential backoff. The notification was not delivered. |