Zinnia Illustration Generation Service API

What is the Zinnia Illustration Generation Service API?

The Zinnia Illustration Generation Service API is a comprehensive, enterprise-grade solution designed to streamline and automate the generation of insurance product illustrations. It provides a robust, flexible platform for creating detailed financial projections and visualizations for various insurance products.

Core Capabilities

Illustration Request Management
- Synchronous and Asynchronous illustration processing
- Multiple output format support
- Detailed request tracking
- Flexible input parameter handling
Calculation Processing
- Complex financial modeling
- Policy state simulation
- Multiple scenario generation
- Precise numeric calculations
Output Generation
- Raw numeric illustrations
- Formatted PDF reports
- Comprehensive financial metrics
Performance Optimization
- Queued processing
- Scalable architecture
- Efficient calculation engines
- Parallel processing support
Reporting and Analytics
- Detailed calculation metrics
- Request status tracking
- Error logging and diagnostics
- Performance monitoring

Key Features and Benefits

Why Use This API?

Digital Transformation

Advanced Calculation Engine: Powerful, flexible illustration generation capable of in-force, new-business, and administration calculations
API-First Architecture: Modern, scalable design
Standardization: Consistent calculation methodologies

Enhanced User Experience


  graph LR
    A[Instant Illustrations] --> B[Multiple Formats]
    B --> C[Detailed Projections]
    C --> D[User Empowerment]
    D --> E[Informed Decisions]

Rapid Processing: Generate raw results in fractions of a second, compliant illustrations in seconds
Flexible Outputs: PDF, raw values as JSON, addtional formats planned
Comprehensive Insights: Detailed financial projections, including monthly values projection
Self-Service Capabilities: Enable direct user interactions

Operational Efficiency


  graph TB
    subgraph Benefits
        A[Calculation Speed] --> B[Resource Optimization]
        B --> C[Reduced Manual Work]
        C --> D[Consistent Results]
    end
    
    subgraph Metrics
        E[Processing Time -80%]
        F[Manual Effort -90%]
        G[Accuracy Improvement 99%]
    end

Faster Illustrations: Dramatically reduce calculation times
Reduced Overhead: Minimize manual intervention
Consistent Calculations: Same calcuations used for illustration, quote, and administration
Resource Efficiency: Optimize computational resources

Compliance and Security

Regulatory Compliance: Built-in financial calculation standards
Data Security: Enterprise-grade security measures
Audit Trails: Comprehensive request logging
Access Control: Federated Authentication and Fine Grained Authorization Control

Architecture Overview


  flowchart TD
    A[Illustration Request] --> B{Async/Sync Processing}
    B -->|Async| C[Queue Management]
    B -->|Sync| D[Immediate Calculation]
    C --> E[Calculation Engine]
    D --> E
    E --> F[Result Generation]
    F --> G{Output Format}
    G -->|Raw Values| H[Numeric Data]
    G -->|PDF| I[Formatted Report]
    H & I --> J[Result Storage]
    J --> K[Status Tracking]

API Specifications

Authentication

All API endpoints require authentication using Auth0. Include a valid access token in the Authorization header:

Authorization: Bearer <your_access_token>

Core Endpoints

1. Asynchronous Illustration Request

POST /illustration/v3/illustration-request

Submit an illustration request for asynchronous processing.

Request Body - Simplified:

{
    "illustrationType": "INFORCE",
    "calculationType": "SINGLE_ILLUSTRATION",
    "policyDetail": {
      "attributes": {
        "carrierCode": "EGL",
        "productCode": "EGLUL1",
        "productType": "UNIVERSALLIFE",
        "planName": "Evarglades Life UL",
        "qualifiedPlanType": "Non-Qualified",
        "payToYear": "20",
        "policyYear": "4",
        "policyNumber": "ABC123DEF",
        "policyStatus": "ACTIVE",
        "jurisdiction": "CT",
        "effectiveDate": "2021-04-10",
        "issueDate": "2021-04-10"
      },
      "accountValue": {
        "attributes": {
          "beginningAccountValue": "43201.913097",
          "cashValueByYear": "41927.823217",
          "cashSurrenderValue": "43201.913097",
          "netAmountAtRisk": "706728.904236"
        },
        "policyMetrics": {
          "attributes": {
            "initialPaymentAmount": "1225.290000",
            "grossPremiumAmountSinceIssue": "42885.150000",
            "projectedLapseIndicator": "No"
          }
        },
        "loan": {
          "attributes": {
            "loanBalance": "0.000000",
            "maximumAvailableLoan": "43201.913097"
          }
        },
        "withdrawal": {
          "attributes": {
            "totalWithdrawalAmountSinceIssue": "0.000000",
            "maximumWithdrawalAmount": "43201.913097"
          }
        }
      }
    },
    "projection": {
      "attributes": {
        "policyDetailDate": "2024-04-22",
        "illustrationRequestDate": "2024-04-22"
      }
    }
}

Response:

{
  "requestId": "abc123def",
}

2. Illustration Request Status

GET /illustration/v3/illustration-request/{id}

Retrieve the status of a specific illustration request.

Response:

{
  "requestId": "ILLUST-2024-00001",
  "formatStatuses": [
    {
      "format": "RAW_ILLUSTRATION_VALUES",
      "status": "COMPLETE"
    },
    {
      "format": "FORMATTED_ILLUSTRATION_PDF",
      "status": "PENDING"
    }
  ]
}

3. Retrieve Illustration Results

GET /illustration/v3/illustration-request/{id}/results/{format}

Retrieve results for a specific illustration request and format.

Supported Formats:

RAW_ILLUSTRATION_VALUES
FORMATTED_ILLUSTRATION_PDF

Endpoint Example Payloads

The following examples are simplified in order to provide a general understanding of the data being exchanged. For complete, authoritative samples please refer to the API specification in the developer portal.

1. Async Illustration Request Payload (As-Is Inforce) - Simplified

{
    "illustrationType": "INFORCE",
    "calculationType": "SINGLE_ILLUSTRATION",
    "policyDetail": {
      "attributes": {
        "carrierCode": "EGL",
        "productCode": "EGLUL1",
        "productType": "UNIVERSALLIFE",
        "planName": "Evarglades Life UL",
        "qualifiedPlanType": "Non-Qualified",
        "payToYear": "20",
        "policyYear": "4",
        "policyNumber": "ABC123DEF",
        "policyStatus": "ACTIVE",
        "jurisdiction": "CT",
        "effectiveDate": "2021-04-10",
        "issueDate": "2021-04-10"
      },
      "accountValue": {
        "attributes": {
          "beginningAccountValue": "43201.913097",
          "cashValueByYear": "41927.823217",
          "cashSurrenderValue": "43201.913097",
          "netAmountAtRisk": "706728.904236"
        },
        "policyMetrics": {
          "attributes": {
            "initialPaymentAmount": "1225.290000",
            "grossPremiumAmountSinceIssue": "42885.150000",
            "projectedLapseIndicator": "No"
          }
        },
        "loan": {
          "attributes": {
            "loanBalance": "0.000000",
            "maximumAvailableLoan": "43201.913097"
          }
        },
        "withdrawal": {
          "attributes": {
            "totalWithdrawalAmountSinceIssue": "0.000000",
            "maximumWithdrawalAmount": "43201.913097"
          }
        }
      }
    },
    "projection": {
      "attributes": {
        "policyDetailDate": "2024-04-22",
        "illustrationRequestDate": "2024-04-22"
      }
    }
}

2. Async Illustration Status Response

{
  "requestId": "ILLUST-2024-00001",
  "formatStatuses": [
    {
      "format": "RAW_ILLUSTRATION_VALUES",
      "status": "PENDING"
    },
    {
      "format": "FORMATTED_ILLUSTRATION_PDF",
      "status": "COMPLETE"
    }
  ]
}

3. Illustration Results Payload - Simplified

{
  "requestId": "ILLUST-2024-00001",
  "calculationIllustration": {
    "policyDetail": {
      "accountValue": {
        "attributes": {
          "beginningAccountValue": "43201.913097",
          "cashValueByYear": "41927.823217",
          "cashSurrenderValue": "43201.913097"
        },
        "policyMetrics": {
          "attributes": {
            "initialPaymentAmount": "1225.290000",
            "grossPremiumAmountSinceIssue": "42885.150000"
          }
        }
      }
    },
    "projection": {
      "results": {
        "assumed": {
          "annualAccountValue": [
              "0.00"
              "75000.00",
              "125000.000"
          ],
          "deathBenefit": [
              "1000000.00",
              "1000000.00"
          ],
          "policyYear":[
              "1",
              "2",
              "3"
          }
        }
      ]
    }
  }
}

4. Error Response Example

{
  "errorCode": "ILLUST_400",
  "message": "Invalid illustration request",
  "details": [
    "Policy number does not match carrier records",
    "Insufficient account value for requested projection"
  ]
}

Supported Output Formats

RAW_ILLUSTRATION_VALUES: Detailed numeric calculation results
FORMATTED_ILLUSTRATION_PDF: Compliant PDF report for client presentation

Payload Validation Guidelines

Request Payload Validation
- Ensure all required fields are present
- Validate data types and ranges
- Check enum values for specific fields
- Verify numerical constraints
Response Payload Consistency
- Always check the status before retrieving Asynchronous results
- Always use the unique request identifier
- Provides comprehensive error details
- Maintains consistent structure across responses
Security Considerations
- Sanitize all input data
- Mask sensitive information
- Implement rate limiting

Common Validation Constraints

Validation contraints are generally product specific, however some common patterns emerge. The following typically have range constraints:

Initial Premium
Projection Years
Fund Allocation

Best Practices

Request Management
- Use asynchronous processing for PDF results
- Use synchronous processing for raw values
- Implement robust error handling
- Cache and reuse calculation results when possible
Performance Optimization
- Limit concurrent illustration requests
- Implement request timeout mechanisms
Security Considerations
- All calculation endpoints are secured via FGA
- Proper rights assigment managed by CIAM team
- Endpoints require TLS encrypted connections

Error Handling

Common error scenarios:

Invalid Request

{
  "error": "INVALID_REQUEST",
  "message": "Missing required calculation parameters",
  "code": 400
}

Authentication Error

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired access token",
  "code": 401
}

Integration Guide

Authentication Setup
- Configure Auth0 integration
- Manage access tokens securely
- Implement token refresh mechanism
API Usage
- Follow rate limiting guidelines
- Implement robust error handling
- Handle asynchronous operations
Monitoring
- Implement comprehensive logging
- Track API performance metrics
- Set up alerts for critical errors
Testing
- Develop integration tests
- Perform load testing
- Validate calculation scenarios
- Test error recovery mechanisms