Push notification REST API

One REST API sends push notifications to Android, iOS and web browsers. Your backend needs three things from App settings in the dashboard:

Both URL styles work: /api/v1/notifications and /notifications are the same endpoint.

Authentication#

Endpoints that send or read data need the app's REST API key in the Authorization header. Any of these forms is accepted:

Authorization: Basic YOUR_REST_API_KEY
Authorization: Key YOUR_REST_API_KEY
Authorization: Bearer YOUR_REST_API_KEY

Device endpoints used by the apps and the web SDK (create device, update device, sessions, click tracking, in-app messages) only need app_id. Never put the REST API key inside your app or website.

Errors#

Errors come as a JSON list with an HTTP status of 400, 402, 403, 404 or 500:

{ "errors": ["You must include which players, segments, or filters to send this notification to."] }

A send that matches nobody returns HTTP 200 with an explanation:

{ "id": "", "recipients": 0, "external_id": null, "errors": ["All included players are not subscribed"] }

Quick start#

curl -X POST https://pushix.in/api/v1/notifications \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_REST_API_KEY" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "included_segments": ["Subscribed Users"],
    "headings": {"en": "Bonus unlocked"},
    "contents": {"en": "Your cart is waiting. Complete your order today and get free delivery."},
    "data": {"screen": "orders"}
  }'

Response:

{ "id": "b98881cc-1e94-4366-bbd9-db8f3429292b", "recipients": 1250, "external_id": null }

That one call reaches every subscribed Android phone, iPhone and browser. The same call from PHP:

$payload = [
    'app_id' => 'YOUR_APP_ID',
    'included_segments' => ['Subscribed Users'],
    'headings' => ['en' => 'Bonus unlocked'],
    'contents' => ['en' => 'Your cart is waiting.'],
    'data' => ['screen' => 'orders'],
];
$ch = curl_init('https://pushix.in/api/v1/notifications');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Basic YOUR_REST_API_KEY'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

A ready-made helper class is in libraries/php/PushixClient.php.

Notifications#

Create notification#

POST /api/v1/notifications — REST API key required.

Targeting#

Use exactly one of these: segments, filters, or ids. They cannot be combined.

Id lists accept up to 10,000 entries per request.

Platforms#

By default a message goes to every platform the app has set up. Narrow it with platform flags or a plain list:

Silent messages (content_available) never go to browsers, because browsers must always show something.

Content#

Each device gets the language that matches its system language (hi, bn, ...), falling back to en.

Personalise text with the device's tags:

"contents": {"en": "Hi {{ name | default: 'friend' }}, you have {{ points }} reward points"}

{{ external_id }} and {{ player_id }} also work.

Android#

iOS#

iPhone messages go through Firebase Cloud Messaging with an APNs payload, so the app needs the Firebase key plus an APNs key uploaded to Firebase (see the iOS SDK or Flutter SDK guide).

Web#

Delivery#

Response#

{ "id": "b98881cc-1e94-4366-bbd9-db8f3429292b", "recipients": 1250, "external_id": null }

recipients is the number of subscribed devices that match right now. Sending happens in the background: small sends go out within seconds; large sends are processed in batches of 500 by the worker.

Examples#

Send to your own user ids, only on their phones:

{
  "app_id": "YOUR_APP_ID",
  "include_external_user_ids": ["10234", "10235"],
  "isAnyWeb": false,
  "headings": {"en": "Order shipped"},
  "contents": {"en": "₹250 has been sent to your UPI ID."},
  "data": {"screen": "orders", "id": "OD-4821"}
}

Users with a tag above a value, or who haven't opened the app in two days:

{
  "app_id": "YOUR_APP_ID",
  "contents": {"en": "Your daily spin is ready"},
  "filters": [
    {"field": "tag", "key": "level", "relation": ">", "value": "5"},
    {"operator": "OR"},
    {"field": "last_session", "relation": ">", "hours_ago": "48"}
  ]
}

Scheduled, with buttons, a picture, an iOS badge and a website link:

{
  "app_id": "YOUR_APP_ID",
  "included_segments": ["Active Users"],
  "excluded_segments": ["Test Users"],
  "headings": {"en": "Diwali offer", "hi": "दिवाली ऑफ़र"},
  "contents": {"en": "Flash sale: 50% off today only", "hi": "आज ही 50% की छूट"},
  "big_picture": "https://yourdomain.com/img/diwali.jpg",
  "buttons": [{"id": "open", "text": "Open app"}, {"id": "share", "text": "Share"}],
  "ios_badgeType": "Increase", "ios_badgeCount": 1,
  "web_url": "https://yourdomain.com/diwali",
  "send_after": "2026-11-08 10:00:00 GMT+0530",
  "throttle_rate_per_minute": 2000
}

From a template, with one value filled in:

{ "app_id": "YOUR_APP_ID", "template_id": "TEMPLATE_ID", "include_external_user_ids": ["10234"] }

Data-only message (nothing shown; your app gets it in addSilentDataListener while open):

{ "app_id": "YOUR_APP_ID", "include_external_user_ids": ["10234"], "content_available": true, "data": {"refresh": "balance"} }

View notification#

GET /api/v1/notifications/{id}?app_id=YOUR_APP_ID — REST API key required.

{
  "id": "b98881cc-1e94-4366-bbd9-db8f3429292b",
  "app_id": "YOUR_APP_ID",
  "status": "completed",
  "contents": {"en": "Your cart is waiting."},
  "headings": {"en": "Bonus unlocked"},
  "data": {"screen": "orders"},
  "included_segments": ["Subscribed Users"],
  "platforms": ["android", "ios", "web"],
  "recipients": 1250,
  "successful": 1231,
  "failed": 17,
  "errored": 2,
  "converted": 140,
  "remaining": 0,
  "queued_at": 1793280000,
  "send_after": 1793280000,
  "completed_at": 1793280011,
  "canceled": false,
  "platform_delivery_stats": {
    "android": {"successful": 900, "failed": 12, "errored": 2, "converted": 104},
    "ios": {"successful": 250, "failed": 3, "errored": 0, "converted": 25},
    "web_push": {"successful": 81, "failed": 2, "errored": 0, "converted": 11}
  },
  "template_id": null,
  "error": null
}

List notifications#

GET /api/v1/notifications?app_id=YOUR_APP_ID&limit=50&offset=0 — REST API key required.

limit is at most 50. Add kind=0 for dashboard sends only or kind=1 for API sends only.

{ "total_count": 312, "offset": 0, "limit": 50, "notifications": [ ... ] }

Cancel notification#

DELETE /api/v1/notifications/{id}?app_id=YOUR_APP_ID — REST API key required.

Cancels a scheduled message, or stops one that is still sending. Returns {"success": true}.

Track open#

PUT /api/v1/notifications/{id} — called by the SDKs when a notification is clicked.

{ "app_id": "YOUR_APP_ID", "player_id": "DEVICE_ID", "opened": true, "action_id": "claim" }

Templates#

Saved messages you can send by id. Create them in the dashboard (composer → Save as template) or here.

All need the REST API key. Send with "template_id" on Create notification.

Filters#

Filters are an array. Rules next to each other must all match (AND). {"operator": "OR"} starts a new group.

Examples:

[{"field": "tag", "key": "plan", "relation": "=", "value": "gold"}]
[{"field": "platform", "relation": "=", "value": "ios"}, {"field": "last_session", "relation": ">", "hours_ago": "72"}]
[{"field": "external_user_id", "relation": "not_exists"}]

Segments#

Built-in segments#

Create segment#

POST /api/v1/apps/{app_id}/segments — REST API key required.

{ "name": "Gold members", "filters": [{"field": "tag", "key": "plan", "relation": "=", "value": "gold"}] }

Returns {"success": true, "id": "SEGMENT_ID"}. Segments are evaluated at send time, so new devices that match are included automatically.

List segments#

GET /api/v1/apps/{app_id}/segments?limit=300&offset=0 — REST API key required.

Delete segment#

DELETE /api/v1/apps/{app_id}/segments/{segment_id} — REST API key required.

Devices (players)#

A device is one app install or one browser. Its id is also called the player id or subscription id.

Add a device#

POST /api/v1/players — app_id only. The SDKs call this for you.

Returns {"success": true, "id": "DEVICE_ID"}. Registering the same token or endpoint again returns the same id, so reinstalls don't create duplicates.

Edit a device#

PUT /api/v1/players/{id} — app_id only. Same fields as above. A tag value of "" deletes that tag. "clear_tags": true removes all tags first.

Sessions#

POST /api/v1/players/{id}/on_session — counts a new app open, updates last_active and resets the iOS badge count (unless the body sends badge_count, which is then stored as is). Same body as edit.

POST /api/v1/players/{id}/on_focus with {"app_id": "...", "state": "ping", "active_time": 60} adds seconds spent in the app.

View a device#

GET /api/v1/players/{id}?app_id=YOUR_APP_ID — REST API key required.

{
  "id": "5c6c4b1e-4f0e-4a5e-9a3b-0d3c3c8f2a11",
  "identifier": "fcm-token…",
  "platform": "android",
  "device_type": 1,
  "session_count": 14,
  "language": "hi",
  "timezone": 19800,
  "game_version": "2.4.0",
  "device_os": "14",
  "device_model": "Xiaomi Redmi Note 12",
  "tags": {"level": "5"},
  "badge_count": 0,
  "last_active": 1793280000,
  "playtime": 3600,
  "amount_spent": 0,
  "created_at": 1790000000,
  "invalid_identifier": false,
  "external_user_id": "10234",
  "notification_types": 1,
  "subscribed": true
}

List devices#

GET /api/v1/players?app_id=YOUR_APP_ID&limit=300&offset=0 — REST API key required. Newest first, limit at most 300.

Delete a device#

DELETE /api/v1/players/{id}?app_id=YOUR_APP_ID — REST API key required.

Import devices#

POST /api/v1/apps/{app_id}/players/import — REST API key required. Up to 2000 per request.

{ "players": [ {"id": "OLD-PLAYER-ID", "identifier": "fcm-token", "device_type": 1, "external_user_id": "10234", "tags": {"level": "5"}} ] }

Keeps the original ids. Android rows are imported; iOS and web subscribers register again when they next open your app or site. The dashboard's “Import CSV” button (Subscribers) uses this with a CSV export of your subscribers.

Users (external user id)#

Edit tags for a user#

PUT /api/v1/apps/{app_id}/users/{external_user_id} — REST API key required. Updates every device of that user.

{ "tags": {"balance": "250", "kyc": "done", "old_tag": ""} }

Returns {"success": true, "devices_updated": 2}.

View a user's devices#

GET /api/v1/apps/{app_id}/users/{external_user_id} — REST API key required.

SDK endpoints#

Called by the Pushix SDKs (Flutter, Android, iOS, React Native, web) with app_id only. Browsers may call them from any website (CORS is open on these paths).

If the organization's plan doesn't include in-app messages, the in-app list is empty (no error), so apps keep working.

App#

GET /api/v1/apps/{app_id} — REST API key required. Returns players (all devices) and messageable_players (subscribed).

What's supported#