Notify! API Documentation

Public endpoints for device and group messaging. Documented here: GET /link, GET/POST /notify/{deviceId}, GET/POST /notify-group/{groupId}, and POST /notify-json/{id} 🆕.

GET

/link

Validate a device or group using id + token

▶

Parameters

⚠️ Rate Limit: This endpoint is limited to 5 calls per minute per IP address.

Name	In	Type	Required	Description
`id`	query	string	required	Device or group ID
`token`	query	string	required	Matching device/group token

Request

GET /link?id=ABC12345&token=XYZ789TOKEN123

Use this for integration tests or setup flows.

cURL

curl "https://notifypush.pingie.com/link?id=ABC12345&token=XYZ789TOKEN123"

Responses

{
  "success": true,
  "type": "device",
  "device": {
    "id": "ABC12345",
    "name": "iPhone (iOS 17.0)",
    "notification_url": "https://notifypush.pingie.com/notify/ABC12345",
    "last_active": "2024-12-28T10:30:00Z",
    "platform": "iOS",
    "os_version": "17.0"
  }
}

{
  "success": true,
  "type": "group",
  "group": {
    "id": "GRP56789",
    "name": "Family Notifications",
    "notification_url": "https://notifypush.pingie.com/notify-group/GRP56789",
    "last_active": "2024-12-28T10:30:00Z",
    "member_count": 3,
    "created_at": "2024-12-01T08:00:00Z"
  }
}

Error: 404 invalid id/token pair • 429 rate limit exceeded (5 calls/minute)

POST

/notify-json/{id}

✨ Unified JSON endpoint - PREFERRED for all integrations

▶

💡 Recommended Endpoint: This is the preferred method for all modern integrations. It supports both devices and groups, auto-detection, JSON payloads, custom icons, and notification threading.

⚠️ Important: Requests must include Content-Type: application/json header for the body to be parsed correctly.

Overview

Auto-detects device vs group based on ID format (GRP* = group). Supports webhook icons and threading.

Parameters

Name	In	Type	Required	Description
`id`	path	string	required	Device or group ID (auto-detected)
`token`	query	string	required	Device or group token
`text`	JSON body	string	required	Notification message (no URL encoding needed)
`title`	JSON body	string	optional	Notification title
`groupType`	JSON body	string	optional	Identifier that controls notification threading/grouping
`iconUrl`	JSON body	string	optional	Custom icon URL for webhook notifications

Device Notification

POST /notify-json/ABC12345?token=XYZ789TOKEN123
Content-Type: application/json

{
  "text": "Server CPU at 95%! 🔥"
}

Group Notification

POST /notify-json/GRP45678?token=GRPTOKEN456
Content-Type: application/json

{
  "text": "Database maintenance starting in 30 minutes"
}

cURL Examples

Device notification:

curl -X POST "https://notifypush.pingie.com/notify-json/ABC12345?token=XYZ789TOKEN123" \
  -H "Content-Type: application/json" \
  -d '{"text": "Server CPU at 95%! 🔥"}'

Group notification:

curl -X POST "https://notifypush.pingie.com/notify-json/GRP45678?token=GRPTOKEN456" \
  -H "Content-Type: application/json" \
  -d '{"text": "Database maintenance starting in 30 minutes"}'

Webhook Notifications with Custom Icons

🎨 Thread Grouping: The groupType parameter controls notification threading - notifications with the same groupType will be grouped together in their own thread, while different values create separate threads.

Basic webhook (default thread):

curl -X POST "https://notifypush.pingie.com/notify-json/DEVICE_ID?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Server restarted"}'

GitHub notifications (grouped in one thread):

curl -X POST "https://notifypush.pingie.com/notify-json/DEVICE_ID?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Deploy succeeded",
    "title": "GitHub Actions",
    "groupType": "github-ci",
    "iconUrl": "https://github.com/favicon.ico"
  }'

Jenkins notifications (separate thread from GitHub):

curl -X POST "https://notifypush.pingie.com/notify-json/DEVICE_ID?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Build #142 passed",
    "title": "Jenkins",
    "groupType": "jenkins-ci",
    "iconUrl": "https://jenkins.io/favicon.ico"
  }'

Malformed JSON handling:

curl -X POST "https://notifypush.pingie.com/notify-json/DEVICE_ID?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{bad json here}'

# Returns: 400 Bad Request
# {
#   "error": "Bad Request",
#   "message": "Invalid JSON in request body",
#   "details": "..."
# }

Custom Icons

When iconUrl is provided, Notify! attempts to load the custom icon. If unavailable, it falls back to a generic icon to ensure notifications always display properly.

Device Response

{
  "success": true,
  "type": "device",
  "deviceId": "ABC12345",
  "message": "Notification sent successfully"
}

Group Response

{
  "success": true,
  "type": "group",
  "groupId": "GRP45678",
  "groupName": "DevOps Team",
  "message": "Group notification sent",
  "deviceCount": 3,
  "successCount": 3,
  "failureCount": 0,
  "results": [
    {"deviceId": "ABC12345", "success": true},
    {"deviceId": "DEF67890", "success": true},
    {"deviceId": "GHI23456", "success": true}
  ]
}

Error Response

{
  "error": "Bad Request",
  "message": "Missing required field: text",
  "required": ["text"],
  "optional": ["title", "iconUrl", "groupType"]
}

Errors: 400 missing text field or invalid JSON • 403 invalid token • 404 ID not found • 415 missing or incorrect Content-Type header

Key Points

Single endpoint: /notify-json/{id}
Required: Must include Content-Type: application/json header
Auto-detects device vs group based on ID (GRP* = group)
Returns "type" field so you know what was processed
No URL encoding needed for the message text
Supports webhook icons via iconUrl parameter (case-sensitive)
Threading: Use groupType to group notifications - same type = same thread, different type = separate threads (case-sensitive)
Robust icon fallback ensures webhook notifications always display properly

GET

POST

/notify/{deviceId}

Send a notification to a single device

▶

Parameters

ℹ️ Note: Both GET and POST methods are supported with identical parameters.

✨ NEW: Now supports title, iconUrl, and groupType for enhanced notifications!

Name	In	Type	Required	Description
`deviceId`	path	string	required	Target device ID
`token`	query	string	required	Device token
`body`	query	string	required	Notification message. URL‑encode if sent in query/form.
`title`	query	string	optional	Custom notification title (URL-encode)
`iconUrl`	query	string	optional	Custom icon URL (must be HTTPS, URL-encode)
`groupType`	query	string	optional	Thread identifier for grouping notifications

Request Examples

Basic notification (GET):

GET /notify/ABC12345?token=XYZ789TOKEN123&body=Hello%20World

Enhanced notification with all features (GET):

GET /notify/ABC12345?token=TOKEN&body=Server%20CPU%20at%2095%25&title=Alert&groupType=monitoring&iconUrl=https%3A%2F%2Fexample.com%2Ficon.png

cURL Examples

Basic notification:

curl "https://notifypush.pingie.com/notify/ABC12345?token=XYZ789TOKEN123&body=Hello%20World"

Enhanced with custom title and icon:

curl "https://notifypush.pingie.com/notify/ABC12345?token=TOKEN&body=Server%20down&title=Critical%20Alert&iconUrl=https://example.com/alert.png&groupType=server-alerts"

Using POST with threading:

curl -X POST "https://notifypush.pingie.com/notify/ABC12345?token=TOKEN&body=Build%20passed&title=CI/CD&groupType=github-actions"

Responses

{
  "success": true,
  "deviceId": "ABC12345",
  "message": "Notification sent successfully",
  "apnsId": "12345678-1234-1234-1234-123456789012"
}

Errors: 403 invalid device token • 404 device not found

GET

POST

/notify-group/{groupId}

Send a notification to all devices in the group

▶

Parameters

ℹ️ Note: Both GET and POST methods are supported with identical parameters.

✨ NEW: Now supports title, iconUrl, and groupType for enhanced notifications!

Name	In	Type	Required	Description
`groupId`	path	string	required	Target group ID
`token`	query	string	required	Group token
`body`	query	string	required	Notification message. URL‑encode if sent in query/form.
`title`	query	string	optional	Custom notification title (URL-encode)
`iconUrl`	query	string	optional	Custom icon URL (must be HTTPS, URL-encode)
`groupType`	query	string	optional	Thread identifier for grouping notifications

Request Examples

Basic group notification (GET):

GET /notify-group/GRP56789?token=GROUP_TOKEN&body=Hello%20team!

Enhanced notification with all features (GET):

GET /notify-group/GRP56789?token=TOKEN&body=Deploy%20complete&title=DevOps&groupType=deployments&iconUrl=https%3A%2F%2Fexample.com%2Fcheck.png

cURL Examples

Basic group notification:

curl "https://notifypush.pingie.com/notify-group/GRP56789?token=GROUP_TOKEN&body=Hello%20team!"

Enhanced with custom title and icon:

curl "https://notifypush.pingie.com/notify-group/GRP56789?token=TOKEN&body=Deployment%20successful&title=Production&iconUrl=https://example.com/success.png&groupType=prod-deploys"

Using POST with threading:

curl -X POST "https://notifypush.pingie.com/notify-group/GRP56789?token=TOKEN&body=All%20tests%20passed&title=CI/CD&groupType=test-results"

Responses

{
  "success": true,
  "groupId": "GRP56789",
  "message": "Notification sent to 3 devices"
}

Errors: 403 invalid group token • 404 group not found

Tips. For modern integrations, use POST /notify-json/{id} with JSON body. For query-based calls, URL‑encode body parameter. Both GET and POST methods work for legacy notification endpoints. Keep messages short to avoid truncation. Use GET /link first to verify credentials.

🚀 Quick Start

1. Download Notify! from the App Store
2. Get your device ID and token from the app
3. Send your first notification using the examples above
4. Check out our automation integrations for no-code solutions