Notifications API

The Notifications API enables you to send messages across multiple channels including SMS, email, WhatsApp, and in-app notifications. Use this API to engage with users through their preferred communication methods.

Available Notification Channels

SMS Notifications

Send text messages to mobile devices using the SMS endpoint:

POST /Sms/Send
{
  "body": "Your verification code is 123456",
  "sendTo": [
    {
      "address": "0123456789",
      "countryCode": "ZA"
    }
  ]
}

Email Notifications

Send emails with the following options:

1. Direct Email - Send customized emails with HTML or plain text content

   POST /EmailNotification/SendNotification
   {
     "subject": "Account Verification",
     "plainTextContent": "Please verify your account",
     "htmlContent": "<h1>Verify your account</h1><p>Click the link below to verify</p>",
     "to": "user@example.com",
     "recipientName": "John Doe",
     "from": "no-reply@lightstone.co.za",
     "fromName": "Lightstone Support"
   }

2. Template Email - Send emails using SendGrid templates

   POST /EmailNotification/SendSendGridEmailTemplate
   {
     "from": "no-reply@lightstone.co.za",
     "fromName": "Lightstone Support",
     "recipients": ["user@example.com"],
     "templateId": "d-template-id-from-sendgrid",
     "templateData": {
       "name": "John",
       "verificationLink": "https://example.com/verify/123456"
     }
   }

WhatsApp Notifications

Send WhatsApp messages with either:

1. Text Only Messages

   POST /WhatsApp/Send/TextOnly
   {
     "authToken": "your-whatsapp-auth-token",
     "phoneNumberId": "your-whatsapp-phone-number-id",
     "sendToPhoneNumber": "0123456789",
     "countryCode": "ZA",
     "messageBody": "Your verification code is 123456"
   }

2. Template Messages - For pre-approved message templates

   POST /WhatsApp/Send/Template
   {
     "authToken": "your-whatsapp-auth-token",
     "phoneNumberId": "your-whatsapp-phone-number-id",
     "sendToPhoneNumber": "0123456789",
     "countryCode": "ZA",
     "templateName": "verification_code",
     "languageCode": "en",
     "components": [
       {
         "type": "body",
         "parameters": [
           {
             "type": "text",
             "text": "123456"
           }
         ]
       }
     ]
   }

In-App Notifications

Display notifications within your applications:

1. System Notifications - Retrieve unseen notifications

   GET /Notifications/{notificationType}/unseen?category=CategoryName

2. Mark Notifications as Seen

   POST /Notifications/{name}/seen
   {
     "flagValue": "read"
   }

3. Add Target Users - Target specific users for notifications

   POST /Notifications/{notificationId}/addTargetUsers
   ["user1-id", "user2-id"]

Authentication

All API endpoints require authentication using an API key:

• Include the Ocp-Apim-Subscription-Key header with your API key
• Alternatively, use the subscription-key query parameter

Most endpoints also require:

• correlationid header for request tracking
• x-ls-party-id header to identify the user or party

Required Headers

Header	Description	Required
Ocp-Apim-Subscription-Key	Your API subscription key	Yes
correlationid	Unique identifier for tracking the request	Yes
x-ls-party-id	Party ID of the user or system	Yes
x-Authenticated-TenantId	Tenant identifier for multi-tenant operations	For some endpoints

Response Handling

For most endpoints, successful responses return a 200 OK status code with varying response structures:

• SMS and WhatsApp responses include a status code and message
• Email notifications return a 200 OK with no content when successful

Error Handling

API errors return appropriate HTTP status codes:

• 400 Bad Request - Invalid input parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Valid authentication but insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server-side errors

Error responses include descriptive messages to help troubleshoot issues.

Getting Started

1. Obtain your API key from the Lightstone developer portal
2. Choose the appropriate notification channel for your use case
3. Format your request according to the endpoints documented above
4. Include all required headers
5. Handle the response appropriately based on your application needs

Next Steps

• Explore the complete API reference
• Learn about notification best practices