# WellNuo Notification API Specification **Version**: 1.0 **Date**: 2026-01-27 --- ## Overview WellNuo needs API endpoints to send notifications through 3 channels: 1. **Email** — Alert notifications 2. **SMS** — Emergency alerts 3. **Voice** — Emergency phone calls --- ## Authentication API Key in Authorization header: ``` Authorization: Bearer {API_KEY} ``` --- ## 1. Email API ### Endpoint ``` POST /api/v1/notify/email ``` ### Request ```json { "to": "user@example.com", "subject": "WellNuo Alert: Ferdinand", "body": { "html": "

Alert

Ferdinand has not moved for 7 hours.

", "text": "Alert: Ferdinand has not moved for 7 hours." } } ``` ### Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `to` | string | Yes | Recipient email | | `subject` | string | Yes | Email subject | | `body.html` | string | Yes | HTML content | | `body.text` | string | Yes | Plain text fallback | ### Response ```json { "success": true, "message_id": "msg_abc123" } ``` --- ## 2. SMS API ### Endpoint ``` POST /api/v1/notify/sms ``` ### Request ```json { "to": "+14155552671", "message": "WellNuo Alert: Ferdinand has not moved for 7 hours. Check app for details." } ``` ### Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `to` | string | Yes | Phone number (E.164 format: +1234567890) | | `message` | string | Yes | SMS text (max 1600 characters) | ### Response ```json { "success": true, "message_id": "msg_xyz789" } ``` --- ## 3. Voice API ### Endpoint ``` POST /api/v1/notify/voice ``` ### Request ```json { "to": "+14155552671", "message": "This is an urgent alert from WellNuo. Ferdinand has not moved for 7 hours. Please check on them immediately." } ``` ### Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `to` | string | Yes | Phone number (E.164 format) | | `message` | string | Yes | Text that will be spoken to the user | ### Response ```json { "success": true, "call_id": "call_abc123" } ``` --- ## Error Response All endpoints return errors in this format: ```json { "success": false, "error": { "code": "INVALID_PHONE", "message": "Phone number format is invalid" } } ``` ### Error Codes | Code | HTTP | Description | |------|------|-------------| | `VALIDATION_ERROR` | 400 | Invalid request data | | `INVALID_PHONE` | 400 | Phone number format wrong | | `INVALID_EMAIL` | 400 | Email format wrong | | `UNAUTHORIZED` | 401 | Invalid API key | | `RATE_LIMITED` | 429 | Too many requests | | `SERVER_ERROR` | 500 | Internal error |