Notify! API Documentation

Public endpoints for device and group messaging. Documented here: GET /link, GET/POST /notify/{deviceId}, GET/POST /notify-group/{groupId}, POST /notify-json/{id} 🆕, and notification history endpoints GET /device/notifications 🔒 and GET /group/{groupId}/notifications 🔒 (authentication required).

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://notifyapns.pingie.com/link?id=ABC12345&token=XYZ789TOKEN123"

Responses

{
  "success": true,
  "type": "device",
  "device": {
    "id": "ABC12345",
    "name": "iPhone (iOS 17.0)",
    "notification_url": "https://notifyapns.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://notifyapns.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.

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://notifyapns.pingie.com/notify-json/ABC12345?token=XYZ789TOKEN123" \
  -H "Content-Type: application/json" \
  -d '{"text": "Server CPU at 95%! 🔥"}'

Group notification:

curl -X POST "https://notifyapns.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://notifyapns.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://notifyapns.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://notifyapns.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://notifyapns.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", "priority", "sound", "badge", "metadata", "groupType", "iconUrl"]
}

Errors: 400 missing text field or invalid JSON • 403 invalid token • 404 ID not found

Key Points

Single endpoint: /notify-json/{id}
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.

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.

Request Examples

GET Method:

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

POST Method:

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

cURL

Using GET:

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

Using POST:

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

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.

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.

Request Examples

GET Method:

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

POST Method:

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

cURL

Using GET:

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

Using POST:

curl -X POST "https://notifyapns.pingie.com/notify-group/GRP56789?token=GROUP_TOKEN" \
  --data-urlencode "body=Hello team!"

Responses

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

Errors: 403 invalid group token • 404 group not found

GET

/device/notifications

Get notification history for a device (requires authentication)

▶

Overview

⚠️ Authentication Required: This endpoint requires Bearer token authentication and is intended for server-to-server use only. Never expose the Bearer token in client applications.

Parameters

Name	In	Type	Required	Description
`deviceId`	query	string	required	Target device ID (8 characters)
`limit`	query	integer	optional	Maximum notifications to return (default: 50, max: 200)

Required Headers

Header	Value	Description
`Authorization`	Bearer {token}	Server authentication token

Request

GET /device/notifications?deviceId=ABC12345&limit=50
Authorization: Bearer YOUR_AUTH_TOKEN

cURL

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  "https://notifyapns.pingie.com/device/notifications?deviceId=ABC12345&limit=50"

Source Types

The source field categorizes notification origins:

api - Change detected by monitoring server
notify - Direct push notification via API
group - Group broadcast notification
admin - Sent from admin dashboard

Response

[
  {
    "id": 1234,
    "device_id": "ABC12345",
    "message": "Server CPU at 95%!",
    "sent_at": "2024-12-28T10:30:00Z",
    "success": true,
    "error_message": null,
    "source": "api"
  },
  {
    "id": 1233,
    "device_id": "ABC12345",
    "message": "Website updated",
    "sent_at": "2024-12-28T09:15:00Z",
    "success": true,
    "error_message": null,
    "source": "notify"
  }
]

Errors: 400 missing deviceId • 401 invalid/missing bearer token • 500 server error

GET

/group/{groupId}/notifications

Get notification history for a group (requires authentication)

▶

Overview

⚠️ Authentication Required: This endpoint requires Bearer token authentication and is intended for server-to-server use only. Never expose the Bearer token in client applications.

Parameters

Name	In	Type	Required	Description
`groupId`	path	string	required	Target group ID (e.g., GRP12345)
`limit`	query	integer	optional	Maximum notifications to return (default: 200, max: 200)

Required Headers

Header	Value	Description
`Authorization`	Bearer {token}	Server authentication token

Request

GET /group/GRP12345/notifications?limit=100
Authorization: Bearer YOUR_AUTH_TOKEN

cURL

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  "https://notifyapns.pingie.com/group/GRP12345/notifications?limit=100"

Use Cases

Monitor group notification success rates
Debug delivery failures to specific devices
Maintain audit trail of group communications
Analyze notification patterns and timing
Display group history in admin dashboards

Response

[
  {
    "id": 456,
    "group_id": "GRP12345",
    "message": "Server maintenance alert",
    "sent_at": "2024-12-28T15:30:00Z",
    "success": true,
    "error_message": null,
    "source": "group",
    "success_count": 5,
    "failure_count": 0
  },
  {
    "id": 455,
    "group_id": "GRP12345",
    "message": "Database backup completed",
    "sent_at": "2024-12-28T14:00:00Z",
    "success": false,
    "error_message": "Failed to deliver to 2 device(s)",
    "source": "notify",
    "success_count": 3,
    "failure_count": 2
  }
]

Errors: 401 invalid/missing bearer token • 404 group not found • 500 server error

Note: success is true only when ALL devices received the notification (failure_count = 0)

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