Notifications API

Configure how and when you receive notifications across email, push, SMS, and in-app channels.

Get Notifications

curl "https://api.affilync.com/api/notifications?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Default	Description
limit	int	50	Number of notifications to return (1-100)
offset	int	0	Number of notifications to skip for pagination
unread_only	bool	false	Return only unread notifications
notification_type	string	—	Filter by notification type (e.g., commission_earned, payout_processed)

Response (200):

[
  {
    "id": "notif_abc123",
    "type": "commission_earned",
    "channel": "in_app",
    "title": "Commission Earned",
    "message": "You earned $25.00 from Spring Sale campaign",
    "priority": "normal",
    "status": "sent",
    "action_url": "/campaigns/camp_123",
    "action_label": "View Campaign",
    "entity_type": "campaign",
    "entity_id": "camp_123",
    "read_at": null,
    "created_at": "2026-03-24T10:15:00Z",
    "sent_at": "2026-03-24T10:15:01Z",
    "metadata": {
      "commission_id": "comm_abc123",
      "amount": "25.00",
      "campaign_name": "Spring Sale"
    }
  }
]

Get Notification Preferences

curl https://api.affilync.com/api/notifications/preferences \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "email_enabled": true,
  "email_frequency": "instant",
  "push_enabled": true,
  "sms_enabled": false,
  "in_app_enabled": true,
  "quiet_hours_enabled": false,
  "quiet_hours_start": null,
  "quiet_hours_end": null,
  "quiet_hours_timezone": "UTC",
  "dnd_enabled": false,
  "dnd_start": null,
  "dnd_end": null
}

Update Notification Preferences

curl -X PUT https://api.affilync.com/api/notifications/preferences \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_enabled": true,
    "email_frequency": "daily",
    "push_enabled": true,
    "quiet_hours_enabled": true,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "08:00"
  }'

Frequency Values:

• instant - Send immediately
• daily - Daily digest
• weekly - Weekly digest
• never - Disable notifications

Response (200):

{
  "success": true,
  "message": "Notification preferences updated successfully",
  "preferences": {
    "email_enabled": true,
    "email_frequency": "daily",
    "push_enabled": true,
    "sms_enabled": false,
    "in_app_enabled": true,
    "quiet_hours_enabled": true,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "08:00",
    "quiet_hours_timezone": "UTC",
    "dnd_enabled": false
  }
}

Unread Count

Lightweight endpoint for badge counts.

curl https://api.affilync.com/api/notifications/count \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "unread_count": 5
}

Mark as Read

Mark a specific notification as read.

curl -X POST https://api.affilync.com/api/notifications/{notification_id}/read \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "success": true,
  "message": "Notification marked as read"
}

Mark All as Read

Mark all notifications as read for the current user.

curl -X POST https://api.affilync.com/api/notifications/read-all \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "success": true,
  "message": "Marked 5 notifications as read",
  "count": 5
}

Delete Notification

Delete a specific notification.

curl -X DELETE https://api.affilync.com/api/notifications/{notification_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "success": true,
  "message": "Notification deleted successfully"
}

Send Test Notification

Send a test notification to verify your notification settings.

curl -X POST "https://api.affilync.com/api/notifications/test?channel=email" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Required	Description
channel	string	yes	Notification channel: email, push, sms, or in_app

Response (200):

{
  "success": true,
  "message": "Test notification sent via email",
  "notification_id": "notif_test123"
}

---

Notification Types

Affiliate and brand users see different notification types based on their role.

Affiliate Notifications:

Type	Description
commission_earned	New commission recorded
commission_approved	Commission approved for payout
commission_denied	Commission denied or disputed
payout_processed	Payout completed or failed
campaign_created	New campaign available to join
campaign_launched	Campaign you're part of is now live
campaign_ended	Campaign you're part of has ended
campaign_updated	Campaign details have changed
application_approved	Your campaign application was approved
application_rejected	Your campaign application was rejected
security_alert	Security alert: new login, 2FA change, suspicious activity

Brand Notifications:

Type	Description
campaign_created	Campaign you created is live
campaign_launched	Campaign launch event
campaign_ended	Campaign ended
campaign_updated	Campaign details changed
payout_processed	Affiliate payout completed
application_approved	Affiliate application approved
application_rejected	Affiliate application rejected
security_alert	Security alert: new login, 2FA change, suspicious activity

Notification Categories

Notifications are organized by category for filtering and user preferences:

Category	Description
system	Platform announcements and system events
campaign	Campaign-related notifications
commission	Commission and earnings notifications (affiliates only)
payout	Payment and payout notifications
application	Campaign application status changes
security	Security alerts and authentication events
call_tracking	Call tracking notifications
billing	Billing and subscription notifications
general	General notifications

Notification Channels

Notifications can be delivered via multiple channels:

Channel	Description
email	Email delivery (subject to email preferences)
push	Browser/mobile push notifications
sms	SMS text message (requires phone number)
in_app	In-app notification badge

Admin: Send Notification

Admin only - Send a notification to a specific user.

curl -X POST https://api.affilync.com/api/notifications/admin/send \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_abc123",
    "notification_type": "security_alert",
    "channel": "email",
    "title": "Security Alert",
    "message": "A new login was detected on your account",
    "priority": "high",
    "action_url": "/settings/security",
    "action_label": "Review Activity"
  }'

Parameters:

Parameter	Type	Required	Description
user_id	UUID	yes	Target user ID
notification_type	string	yes	Type of notification
channel	string	yes	Delivery channel (email, push, sms, in_app)
title	string	yes	Notification title
message	string	yes	Notification message
priority	string	no	Priority level: low, normal, high, urgent (default: normal)
action_url	string	no	Optional action link
action_label	string	no	Optional action button text

Response (200):

{
  "success": true,
  "message": "Notification sent successfully",
  "notification_id": "notif_sent123"
}

Error Responses

Invalid Notification Type (400):

{
  "detail": "Invalid notification type: invalid_type"
}

Notification Not Found (404):

{
  "detail": "Notification not found or already read"
}

Unauthorized (401):

{
  "detail": "Not authenticated"
}

Best Practices

1. Respect User Preferences - Always check the user's notification settings before sending
2. Use Categories - Filter notifications by category for better organization
3. Set Priority Appropriately - Use high/urgent only for critical notifications
4. Include Action URLs - Provide direct links to relevant resources when possible
5. Test First - Use the /test endpoint to verify setup before production use
6. Batch Operations - Mark all as read rather than individual notifications when appropriate