Unity Notifications Service - API Documentation

🏠 Home › Unity.Notifications / docs

Unity Notifications Service - API Documentation

Overview

Authentication Methods

SharedSecret (Email & SMS management)

Custom HMAC-based authentication via headers: - x-unity-timestamp — Request timestamp - x-unity-verificationcode — HMAC verification code

JWT Bearer (SMS history & preferences)

Standard JWT Bearer token for authorized user endpoints:

Authorization: Bearer <access_token>

AWS SNS Signature (Webhooks)

AWS SNS message signature validation for Pinpoint and bounce webhooks.

Firehose Access Key (Delivery receipts)

X-Amz-Firehose-Access-Key header for Pinpoint Firehose delivery receipt endpoint.

Email Controller

Route Prefix: /Email

Method Path Auth Description
POST /Email/UploadAttachment SharedSecret Upload email attachment to S3
POST /Email/Validate SharedSecret Validate outbound email message
POST /Email/HandleBounce AWS SNS Signature Handle SES bounce/complaint notifications

POST /Email/UploadAttachment

Upload an email attachment to S3 for later inclusion in outbound emails.

Request Body:

{
  "filename": "report.pdf",
  "contentBase64": "JVBERi0xLjQK..."
}

Response (200 OK):

{
  "contentPath": "s3://bucket/attachments/guid/report.pdf"
}

This is the endpoint consumed by Tasks Service (POST /Email/UploadAttachment).

POST /Email/Validate

Validate an outbound email message without sending it.

Request Body: OutboundEmailMessage

{
  "from": "noreply@directsupply.com",
  "to": ["user@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Task Notification",
  "body": "Plain text body",
  "htmlBody": "<html>...</html>",
  "attachments": [],
  "replyToAddresses": []
}

Response: 200 OK (valid) or 400 Bad Request (validation errors)

POST /Email/HandleBounce

Webhook endpoint for AWS SNS bounce and complaint notifications from SES.

Request Body: AWS SNS notification (JSON)

Processing: 1. Validates SNS message signature 2. Handles subscription confirmation automatically 3. Parses bounce notification for permanent bounces 4. Publishes OutboundEmailBounced event via MassTransit

Response: 200 OK

Home Controller (SMS)

Route Prefix: /Home

Method Path Auth Description
GET /Home/Inbound Query validation Handle inbound SMS (Vonage/Nexmo webhook)
GET /Home/DeliveryReceipt None Handle Vonage delivery receipts
GET /Home/GetSmsPhoneNumberStatus None Get opt-in/opt-out status for a phone
GET /Home/GetConversationHistory JWT Bearer Get SMS conversation history
GET /Home/GetPhoneNumberPreferences None Get preferences for multiple phones
POST/GET /Home/SaveSmsPhoneNumberStatusAs JWT Bearer Save phone preference (user auth)
PUT /Home/SavePhoneNumberStatus SharedSecret Save phone preference (service auth)
GET /Home/TestPhoneNumberPreferenceAge None Health check for preference freshness

GET /Home/GetConversationHistory

Get SMS conversation history for a phone number.

Query Parameters: - phoneNumber (string, required) — E.164 format phone number

Response (200 OK):

[
  {
    "directSupplySenderID": "TELS",
    "externalPhoneNumber": "+15551234567",
    "isOutbound": true,
    "message": "Your work order has been scheduled.",
    "statusName": "Delivered",
    "errorName": null
  }
]

GET /Home/GetSmsPhoneNumberStatus

Get the SMS opt-in/opt-out status for a phone number.

Query Parameters: - phoneNumber (string, required)

Response (200 OK): SmsPhoneNumberStatus enum value

PUT /Home/SavePhoneNumberStatus

Save SMS phone number preference (service-to-service call with SharedSecret auth).

Query Parameters: - phoneNumber (string, required) — E.164 format - status (int, required) — 1=Opted In, 2=Opted Out - senderId (string, required) — Sender identifier - requestor (string, required) — Who requested the change

Response: 200 OK or 400 Bad Request

Pinpoint Controller

Route Prefix: /Pinpoint

Method Path Auth Description
POST /Pinpoint/Inbound AWS SNS Signature Handle inbound SMS from AWS Pinpoint
POST/PUT /Pinpoint/DeliveryReceipt Firehose Access Key Handle delivery receipts from Pinpoint Firehose

POST /Pinpoint/Inbound

Handle inbound SMS messages from AWS Pinpoint via SNS webhook.

Request Body: AWS SNS notification containing Pinpoint SMS payload

Processing: 1. Validates SNS signature 2. Parses Pinpoint message payload 3. Publishes InboundSMS event via BusProxy

Response: 200 OK or 204 No Content

POST/PUT /Pinpoint/DeliveryReceipt

Handle SMS delivery receipts from AWS Pinpoint via Firehose.

Headers: - X-Amz-Firehose-Access-Key — Firehose authentication

Request Body: Firehose payload with base64-encoded records

Processing: 1. Decodes base64 records 2. Parses delivery receipt status 3. Publishes DeliveryReceiptSMS events via BusProxy

Response (200 OK):

{
  "requestId": "guid",
  "timestamp": 1234567890
}

Diagnostics Controller

Route Prefix: /Diagnostics Authorization: None

Method Path Description
GET /Diagnostics/Ping Returns "Pong"

Key Data Contracts

OutboundEmailEnvelope

{
  "applicationCode": "TASKS",
  "signature": "hmac-signature",
  "encryptedOutboundEmailMessageBase64": "base64-encoded-encrypted-or-plain",
  "createdTimestamp": "2026-03-11T12:00:00Z",
  "messageTags": {
    "correlationId": "12345",
    "source": "TaskNotification"
  }
}

OutboundEmailMessage

{
  "from": "noreply@directsupply.com",
  "to": ["user@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Subject line",
  "body": "Plain text body",
  "htmlBody": "<html>Rich HTML body</html>",
  "attachments": [
    {
      "filename": "report.pdf",
      "contentPath": "s3://bucket/path"
    }
  ],
  "replyToAddresses": ["support@directsupply.com"]
}

OutboundSMS

{
  "dsMessageID": "guid",
  "senderID": "TELS",
  "number": "+15551234567",
  "message": "Your work order is scheduled for tomorrow.",
  "requestorName": "TELS Tasks",
  "optInAction": "None"
}

InboundSMS

{
  "recipientID": "TELS",
  "number": "+15551234567",
  "message": "OK",
  "dsMessageID": "guid",
  "timestamp": "2026-03-11T12:00:00Z"
}

OutboundEmailBounced

{
  "bouncedEmailToAddresses": ["bad@example.com"],
  "subject": "Original email subject",
  "messageTags": {
    "correlationId": "12345"
  }
}

Global Response Codes

Code Meaning
200 Success
204 No Content (webhook processed, no action needed)
400 Bad Request — validation error
401 Unauthorized — invalid credentials/token

Notes