Case Message SDK

Case Message API

Send and manage case-related messages with integrated document management

API Version 1.0

Overview

The Case Message API provides a robust external facing endpoint for sending new business case-related messages for life policies. Messages are processed asynchronously through Azure Service Bus queues and conditionally routed to multiple downstream systems (Ascend NewBusiness system and NLG's Agent Portal).

The API handles message validation, storage, document indexing, and intelligent routing based on the message source and content.

Authentication

The Case Message API uses OAuth 2.0 Bearer tokens via Auth0 for authentication. All API requests must include proper authorization headers.

Required Headers

Header	Description	Example
Authorization	OAuth 2.0 Bearer token obtained from Auth0	`Bearer eyJ0eXAiOi...`
Ocp-Apim-Subscription-Key	API Management subscription key for rate limiting and tracking	`a1b2c3d4e5f6...`
Content-Type	Media type of the request body	`application/json`

Obtaining an Access Token

Request a token from your Auth0 tenant using the client credentials flow:

POST https://nlg-<<env>>.auth0.com/oauth/token

Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}",
  "audience": "{api_audience}"
}

Environment-Specific Auth0 Domains

Production:  nlg-prd.auth0.com
UAT:         nlg-uat.auth0.com
SIT:         nlg-sit.auth0.com

Note: The client_id, client_secret, and Ocp-Apim-Subscription-Key credentials will be provided by National Life Group (NLG). Please contact Gillian Davis (gdavis2@nationallife.com) to obtain your credentials for each environment.

IP Whitelisting Required: API access requires IP whitelisting. Please share the public IP range of your consumer application with your NLG Point of Contact to enable access.

Token Caching: Access tokens generated for a specific audience are valid for 24 hours. Tokens should be cached and reused until expiry, as token generation requests are subject to rate limiting.

Example Authenticated Request

POST /message HTTP/1.1
Host: api.nationallife.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...
Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json
Connection: Close

Security Note: Never expose your client credentials or subscription keys in client-side code. All API calls should be made from secure server-side applications.

Base URL

All API endpoints are relative to the environment-specific base URL:

Production:  https://io.nlg.net/app-casemsg-gtw/v1
UAT:         https://uat.io.nlg.net/app-casemsg-gtw/v1
SIT:         https://sit.io.nlg.net/app-casemsg-gtw/v1

Send Message

POST /message

Send a new case message to the system. The message is validated, queued for asynchronous processing, and conditionally routed to multiple downstream systems based on the data source and message content.

Authorization

Authorization: Bearer {token}
Ocp-Apim-Subscription-Key: {subscription_key}

Token Audience (for Auth0)

Production:  https://io.nlg.net/app-casemsg-gtw
UAT:         https://uat.io.nlg.net/app-casemsg-gtw
SIT:         https://sit.io.nlg.net/app-casemsg-gtw

Content-Type: application/json

Message Object (Root)

Property	Type	Required	Description
EmailRequest	object	Required	Container for the email message details
isJunit	boolean	Optional	Testing flag (internal use only)

EmailRequest Object

Property	Type	Required	Description
TransRefGUID	string	Required	Unique transaction reference GUID for tracking
SourceInfo	object	Required	Source system information (determines routing logic)
Email	object	Required	Email content and metadata

SourceInfo Object

Property	Type	Required	Description
SourceInfoName	string	Required	Three character agency code
CreationDate	string	Optional	Date when message was created (YYYY-MM-DD)
CreationTime	string	Optional	Time when message was created (HH:mm:ss)

Email Object

Property	Type	Required	Description
MessageId	string	Required	Unique identifier for the message
ThreadId	string	Required	Thread/conversation identifier
PolicyNumber	string	Conditional	Policy number (either this or HOAssignedAppNumber required)
HOAssignedAppNumber	string	Conditional	Home office assigned application number
Date	string	Required	Message date/time (yyyy-MM-dd hh:mm:ss)
From	string	Required	Sender email address
To	string	Required	Recipient email address(es) - max 500 chars
Cc	string	Optional	CC recipients - max 500 chars
Bcc	string	Optional	BCC recipients - max 500 chars
Subject	string	Required	Email subject - max 500 chars
InReplyToId	string	Optional	Message ID being replied to
Body	object	Required	Email body content
Custom	object	Required	Custom business metadata
Attachments	array	Optional	List of file attachments

Body Object

Property	Type	Required	Description
HTMLData	string	Required	Email body content (HTML format)
EncodeType	string	Required	Encoding type. Values: `Base64`, `Plain`

Custom Object

Property	Type	Required	Description
AgencyNumber	string	Required	Agency identifier
ServicingAgentNumber	string	Required	Servicing agent identifier
SenderName	string	Required	Name of the message sender
TransactionType	string	Required	Type of transaction
LineOfBusiness	string	Required	Business line (e.g., Life, Annuity)
BusinessArea	string	Required	Business area (e.g., New Business, Claims)
UserId	string	Optional	User identifier
OwnerName	string	Optional	Policy owner name

Response Codes

200 Message successfully queued for processing

400 Bad request - Validation errors in request body

401 Unauthorized - Invalid or missing authentication

500 Internal server error - Queue publishing failed

Success Response (200)

{
  "EmailResponse": {
    "TransRefGUID": "550e8400-e29b-41d4-a716-446655440000",
    "Result": "Success",
    "Description": ""
  }
}

Error Response (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "EmailRequest is required"
  }
}

Complete Request Example

{
  "EmailRequest": {
    "TransRefGUID": "550e8400-e29b-41d4-a716-446655440000",
    "SourceInfo": {
      "CreationDate": "2024-01-15",
      "CreationTime": "10:30:00",
      "SourceInfoName": "3IP"
    },
    "Email": {
      "PolicyNumber": "POL123456789",
      "HOAssignedAppNumber": "APP987654321",
      "MessageId": "MSG-2024-001-ABC",
      "ThreadId": "THREAD-2024-001",
      "Date": "2024-01-15 10:30:00",
      "From": "agent@agencyname.com",
      "To": "support@nationallife.com",
      "Cc": "manager@agencyname.com",
      "Subject": "Policy Inquiry - POL123456789",
      "Body": {
        "HTMLData": "PGh0bWw+PGJvZHk+SGVsbG8sIEkgaGF2ZSBhIHF1ZXN0aW9uIGFib3V0IHRoZSBwb2xpY3kuLi48L2JvZHk+PC9odG1sPg==",
        "EncodeType": "Base64"
      },
      "Custom": {
        "AgencyNumber": "3IP",
        "ServicingAgentNumber": "SA005678",
        "SenderName": "John Smith",
        "TransactionType": "Inquiry",
        "LineOfBusiness": "Life",
        "BusinessArea": "New Business",
        "UserId": "jsmith@agencyname.com"
      },
      "NumberOfAttachments": "0"
    }
  }
}

cURL Example

curl -X POST "https://api.nationallife.com/app-casemessage-api/message" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -H "Connection: Close" \
  -d '{
    "EmailRequest": {
      "TransRefGUID": "550e8400-e29b-41d4-a716-446655440000",
      ...
    }
  }'

OnBase Document Management API

The OnBase Document Management API is an internal service used by the Case Message API to index email messages as HTML documents. This enables policy-based document search and retrieval within the OnBase document management system.

Note: This API is called internally by the Case Message API when processing new messages. Direct calls should only be made by authorized system integrations.

OnBase Document Upload

Environment-Specific API Domains

Production:  api.nlg.net
UAT:         api.uat.nlg.net
SIT:         api.sit.nlg.net

Document Limits: Maximum allowed document size is 10 MB. Allowed file types are JPEG, PDF, and PNG.

POST https://api.<<env>>.nlg.net/app-documentmanagement/document

Upload and index a document to the OnBase document management system. The document is stored with searchable keywords including policy number, email type, source, and transaction ID.

Authorization

Token Audience (for Auth0)

Production:  https://api.nlg.net/app-documentmanagement/document
UAT:         https://api.uat.nlg.net/app-documentmanagement
SIT:         https://api.sit.nlg.net/app-documentmanagement

Header	Description	Example
Authorization	OAuth 2.0 Bearer token (audience: OnBase API)	`Bearer eyJ0eXAiOi...`
Ocp-Apim-Subscription-Key	API Management subscription key	`a1b2c3d4e5f6...`
Content-Type	Media type	`application/json`
Connection	Connection handling	`Close`

Content-Type: application/json

OnbaseRequest Object

Property	Type	Required	Description
DocumentType	string	Required	OnBase document type. Value: `E-Mail - Case Messaging`
Document	string	Required	Base64-encoded HTML document content
Extension	string	Required	File extension. Value: `html`
UserID	string	Required	Service account username for OnBase
Keywords	array	Required	Array of searchable keyword key-value pairs

Keyword Object

Property	Type	Required	Description
key	string	Required	Keyword name
value	string	Required	Keyword value

Standard Keywords

Key	Description	Example Value
PolicyNumber	Associated policy number	`POL123456789`
EmailType	Transaction type from the message	`Inquiry`
Source	Always "AgentPortal" for OnBase	`AgentPortal`
TransactionID	Unique UUID for the transaction	`550e8400-e29b-...`
DocOrigin	Original source system name	`RESONANT`

Response Codes

200 Document successfully indexed in OnBase

400 Bad request - Invalid document format or missing fields

401 Unauthorized - Invalid token or subscription key

500 Internal server error - OnBase service unavailable

Success Response

{
  "status": "Success",
  "documentHandle": "12345678",
  "message": "Document indexed successfully"
}

Failure Handling: If the OnBase API call fails, the message is saved to a Dead Message Queue for retry processing. Failed messages can be reprocessed through administrative tools.

Complete Request Example

{
  "DocumentType": "E-Mail - Case Messaging",
  "Document": "PGh0bWw+PHByZT48YnI+RGF0ZTogMjAyNC0wMS0xNSAxMDozMDowMDxicj5Gcm9tOiBhZ2VudEBhZ2VuY3kuY29tPGJyPlRvOiBzdXBwb3J0QG5hdGlvbmFsbGlmZS5jb208YnI+U3ViamVjdDogUG9saWN5IElucXVpcnk8YnI+PGJyPkhlbGxvLCBJIGhhdmUgYSBxdWVzdGlvbi4uLjxicj48L3ByZT48L2h0bWw+",
  "Extension": "html",
  "UserID": "svc_casemessage",
  "Keywords": [
    {
      "key": "PolicyNumber",
      "value": "POL123456789"
    },
    {
      "key": "EmailType",
      "value": "Inquiry"
    },
    {
      "key": "Source",
      "value": "AgentPortal"
    },
    {
      "key": "TransactionID",
      "value": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "key": "DocOrigin",
      "value": "AgentPortal"
    }
  ]
}

Document Content Structure

The Document field contains a Base64-encoded HTML document with the following structure:

<html>
  <pre>
    <br>
    Date: 2024-01-15 10:30:00<br>
    From: agent@agency.com<br>
    To: support@nationallife.com<br>
    Cc: manager@agency.com<br>
    Subject: Policy Inquiry - POL123456789<br>
    <br>
    [Email Body Content]
    <br>
  </pre>
</html>

cURL Example

curl -X POST "https://api.nlg.net/app-documentmanagement/document" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -H "Connection: Close" \
  -d '{
    "DocumentType": "E-Mail - Case Messaging",
    "Document": "PGh0bWw+Li4uPC9odG1sPg==",
    "Extension": "html",
    "UserID": "svc_casemessage",
    "Keywords": [...]
  }'

OnBase Document Retrieval

POST https://api.<<env>>.nlg.net/app-documentmanagement/getdocument

Retrieve a document from the OnBase document management system by policy number and document handle. Returns the Base64-encoded document content along with its MIME type.

Authorization

Token Audience (for Auth0)

Production:  https://api.nlg.net/app-documentmanagement/document
UAT:         https://api.uat.nlg.net/app-documentmanagement
SIT:         https://api.sit.nlg.net/app-documentmanagement

Header	Description	Example
Authorization	OAuth 2.0 Bearer token (audience: OnBase API)	`Bearer eyJ0eXAiOi...`
Ocp-Apim-Subscription-Key	API Management subscription key	`a1b2c3d4e5f6...`
Content-Type	Media type	`application/json`
Connection	Connection handling	`Close`

Content-Type: application/json

GetDocument Request Object

Property	Type	Required	Description
PolicyNumber	string	Required	The policy number associated with the document
documentHandle	string	Required	The OnBase document handle identifier

Request Body Example

{
  "PolicyNumber": "POL123456789",
  "documentHandle": "12345678"
}

Response Codes

200 Document successfully retrieved

400 Bad request - Missing or invalid parameters

401 Unauthorized - Invalid token or subscription key

404 Document not found

500 Internal server error - OnBase service unavailable

Success Response (200)

Returns an array of key-value pairs containing the document content and file type:

[
  {
    "Key": "OnBase Document",
    "Value": "PGh0bWw+PHByZT4uLi48L3ByZT48L2h0bWw+"
  },
  {
    "Key": "File Type",
    "Value": "text/html"
  }
]

Response Array Item

Key	Value Description
OnBase Document	Base64-encoded string content of the document
File Type	MIME type of the document (e.g., `text/html`, `application/pdf`)

cURL Example

curl -X POST "https://api.nlg.net/app-documentmanagement/getdocument" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -H "Connection: Close" \
  -d '{
    "PolicyNumber": "POL123456789",
    "documentHandle": "12345678"
  }'

Example Response

[
  {
    "Key": "OnBase Document",
    "Value": "PGh0bWw+PHByZT48YnI+RGF0ZTogMjAyNC0wMS0xNSAxMDozMDowMDxicj5Gcm9tOiBhZ2VudEBhZ2VuY3kuY29tPGJyPlRvOiBzdXBwb3J0QG5hdGlvbmFsbGlmZS5jb208YnI+U3ViamVjdDogUG9saWN5IElucXVpcnk8YnI+PGJyPkhlbGxvLCBJIGhhdmUgYSBxdWVzdGlvbi4uLjxicj48L3ByZT48L2h0bWw+"
  },
  {
    "Key": "File Type",
    "Value": "text/html"
  }
]

Schema Reference

Complete schema definitions for all request and response objects.

JSON Property Naming: All properties use PascalCase naming convention as shown in the schemas above. The API uses Jackson annotations for JSON serialization with @JsonProperty decorators.