API Reference - Novus API Documentation

Authentication

The Novus API uses a two-step authentication process with custom headers and temporary tokens.

⚠️

Token Expiration: Authentication tokens expire after 5 minutes. Plan your API calls accordingly and implement token refresh logic for longer operations.

Authentication Flow

Request Token: Send credentials via headers to the Token endpoint
Receive Token: Extract the token from the response
Use Token: Include token in headers for subsequent API calls
Refresh Token: Request new token before expiration

Required Headers

Headers Authentication Headers

Token Request Headers

Header	Type	Required	Description
`UserName`	string	Required	Your Novus API username
`Password`	string	Required	Your Novus API password

API Request Headers

Header	Type	Required	Description
`UserName`	string	Required	Your Novus API username
`Password`	string	Required	Your Novus API password
`Token`	string	Required	Valid authentication token from /Token endpoint

Base URLs

The Novus API is available in both QA and Production environments with different base URLs.

QA Environment

Testing

Base URL: https://[CLIENT_URL]/[API_PATH]/WAEPANYL

Use this environment for development and testing your integration.

Production Environment

Live

Base URL: https://[CLIENT_URL]/[API_PATH]

Production environment for live member data retrieval.

ℹ️

Note: Production GetMemberInfo endpoint does not include /WAEPANYL/ in the path.

Rate Limits & Restrictions

🔒

IP Restriction: Access to all API endpoints is restricted by IP address. Ensure your IP is whitelisted before making requests.

Token Expiration: 5 minutes from generation
IP Whitelisting: Required for all environments
Rate Limits: Contact API administrator for specific limits

POST /Token

Retrieve an authentication token for API access.

POST /WAEPANYL/Token

Request Headers

Required Headers

UserName: [YOUR_USERNAME]
Password: [YOUR_PASSWORD]
Content-Type: application/json

Request Body

No request body required for token endpoint.

Response

                                            200 OK - Success Response
                                        

                                            {
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}
                                        

Response Fields

Field	Type	Description
`token`	string	JWT authentication token for API requests
`expires_in`	integer	Token lifetime in seconds (300 = 5 minutes)
`token_type`	string	Token type (always "Bearer")

cURL Example

QA Environment

curl -X POST "https://[CLIENT_URL]/[API_PATH]/WAEPANYL/Token" \
  -H "UserName: [YOUR_USERNAME]" \
  -H "Password: [YOUR_PASSWORD]" \
  -H "Content-Type: application/json"

Production Environment

Production

curl -X POST "https://[CLIENT_URL]/[API_PATH]/WAEPANYL/Token" \
  -H "UserName: [YOUR_USERNAME]" \
  -H "Password: [YOUR_PASSWORD]" \
  -H "Content-Type: application/json"

POST /GetMemberInfo

Retrieve member information and policy details using member identifiers.

POST /WAEPANYL/GetMemberInfo QA only - Production omits /WAEPANYL/

Request Headers

Required Headers

UserName: [YOUR_USERNAME]
Password: [YOUR_PASSWORD]
Token: [VALID_TOKEN]
Content-Type: application/json

Request Body

JSON Request Body

{
  "MembershipID": "123456",
  "MemberSSN": "123-45-6789",
  "DateOfBirth": "1990-01-15",
  "FirstName": "Jane",
  "LastName": "Doe"
}

Request Parameters

Parameter	Type	Required	Description
`MembershipID`	string	Required	Member's unique identification number
`MemberSSN`	string	Required	Member's Social Security Number
`DateOfBirth`	string	Required	Member's date of birth (YYYY-MM-DD format)
`FirstName`	string	Required	Member's first name
`LastName`	string	Required	Member's last name

200 OK - Success Response

Member Information Response

[
  {
    "coveredPersonType": "Member",
    "demographics": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1999-03-19T00:00:00",
      "membershipID": "123456",
      "title": "",
      "suffix": "",
      "middleInitial": "",
      "emailAddressInsured": "jane.doe@company.com",
      "maritalStatus": "Single",
      "height": "",
      "membershipStatus": "ACTIVE",
      "primaryPhoneType": null,
      "primaryPhoneNumber": null,
      "residentialAddress": {
        "streetAddressOrPOBox": "123 Main Street",
        "streetAddress2": "",
        "city": "PLANO",
        "stateOfProvince": "TX",
        "zipCode": "12345"
      }
    },
    "businessAddress": "NO",
    "Products": [
      {
        "carrierPolicyNumber": "G-30280-0",
        "policyNumber": "GTL-130601-01",
        "productCode": "GTL",
        "coverageAmount": "0",
        "riders": [
          {
            "riderName": "CHRONIC ILLNESS RIDER",
            "riderCode": "CIR",
            "coverageAmount": "0"
          }
        ]
      }
    ]
  },
  {
    "coveredPersonType": "Spouse",
    "demographics": null,
    "businessAddress": null,
    "Products": null
  }
]

ℹ️

Empty Response: If no records are found or multiple ambiguous matches exist, the API returns an empty array [].

cURL Example

Complete Request Example

curl -X POST "https://[CLIENT_URL]/[API_PATH]/WAEPANYL/GetMemberInfo" \
  -H "UserName: [YOUR_USERNAME]" \
  -H "Password: [YOUR_PASSWORD]" \
  -H "Token: [VALID_TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "MembershipID": "123456",
    "MemberSSN": "123-45-6789", 
    "DateOfBirth": "1990-01-15",
    "FirstName": "Jane",
    "LastName": "Doe"
  }'

Data Models

Demographics Object

Field	Type	Description	Example
`firstName`	string	Member's first name	"Jane"
`lastName`	string	Member's last name	"Doe"
`dateOfBirth`	string	ISO 8601 datetime format	"1999-03-19T00:00:00"
`membershipID`	string	Unique member identifier	"123456"
`emailAddressInsured`	string\|null	Member's email address	"jane.doe@company.com"
`membershipStatus`	string	Current membership status	"ACTIVE"
`residentialAddress`	object	Member's residential address	See Address Object

Address Object

Field	Type	Description	Example
`streetAddressOrPOBox`	string	Street address or PO Box	"123 Main Street"
`streetAddress2`	string	Additional address line	"Apt 4B"
`city`	string	City name	"PLANO"
`stateOfProvince`	string	State or province code	"TX"
`zipCode`	string	Postal/ZIP code	"12345"

Products Array

Field	Type	Description	Example
`carrierPolicyNumber`	string	Insurance carrier policy number	"G-30280-0"
`policyNumber`	string	Internal policy number	"GTL-130601-01"
`productCode`	string	Product type identifier	"GTL"
`coverageAmount`	string	Coverage amount as string	"50000"
`riders`	array	Array of policy riders	See Riders Object

Error Handling

HTTP Status Codes

Status Code	Meaning	Description	Action
`200`	OK	Request successful	Process response data
`400`	Bad Request	Invalid request format	Check request body and headers
`401`	Unauthorized	Invalid credentials or expired token	Refresh token or check credentials
`403`	Forbidden	IP address not whitelisted	Contact administrator for IP whitelisting
`404`	Not Found	Invalid endpoint URL	Verify endpoint path and environment
`429`	Too Many Requests	Rate limit exceeded	Implement request throttling
`500`	Internal Server Error	Server-side error	Retry after delay, contact support

Error Response Format

                            Error Response Example
                        

                            {
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token has expired or is invalid",
    "details": "Token expired at 2024-03-15T10:30:00Z"
  }
}
                        