---
title: "Illustration Service"
url: "https://developers.zinnia.com/apis/illustration-3-0-8/docs/illustration-service"
image: "https://developers.zinnia.com/_og/d/c_Ocean.satori,title_Illustration+Service,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNFRjc0MDAifX19,p_Ii9hcGlzL2lsbHVzdHJhdGlvbi0zLTAtOC9kb2NzL2lsbHVzdHJhdGlvbi1zZXJ2aWNlIg,s_dZk6o9Sv3US64ZXp.png"
---

# Zinnia Illustration Generation Service API

## [What is the 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](#core-capabilities)

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

## [Key Features and Benefits](#key-features-and-benefits)

### [Why Use This API?](#why-use-this-api)

#### [Digital Transformation](#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](#enhanced-user-experience)

```mermaid
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](#operational-efficiency)

```mermaid
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](#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](#architecture-overview)

```mermaid
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](#api-specifications)

### [Authentication](#authentication)

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

```http
Authorization: Bearer <your_access_token>
```

### [Core Endpoints](#core-endpoints)

#### [1\. Asynchronous Illustration Request](#_1-asynchronous-illustration-request)

```http
POST /illustration/v3/illustration-request
```

Submit an illustration request for asynchronous processing.

**Request Body - Simplified:**

```json
{
    "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:**

```json
{
  "requestId": "abc123def",
}
```

#### [2\. Illustration Request Status](#_2-illustration-request-status)

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

Retrieve the status of a specific illustration request.

**Response:**

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

#### [3\. Retrieve Illustration Results](#_3-retrieve-illustration-results)

```http
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](#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](#_1-async-illustration-request-payload-as-is-inforce-simplified)

```json
{
    "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](#_2-async-illustration-status-response)

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

### [3\. Illustration Results Payload - Simplified](#_3-illustration-results-payload-simplified)

```json
{
  "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](#_4-error-response-example)

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

### [Supported Output Formats](#supported-output-formats)

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

## [Payload Validation Guidelines](#payload-validation-guidelines)

1.  **Request Payload Validation**
    -   Ensure all required fields are present
    -   Validate data types and ranges
    -   Check enum values for specific fields
    -   Verify numerical constraints
2.  **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
3.  **Security Considerations**
    -   Sanitize all input data
    -   Mask sensitive information
    -   Implement rate limiting

### [Common Validation Constraints](#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](#best-practices)

1.  **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
2.  **Performance Optimization**
    -   Limit concurrent illustration requests
    -   Implement request timeout mechanisms
3.  **Security Considerations**
    -   All calculation endpoints are secured via FGA
    -   Proper rights assigment managed by CIAM team
    -   Endpoints require TLS encrypted connections

## [Error Handling](#error-handling)

Common error scenarios:

1.  **Invalid Request**
    
    ```json
    {
      "error": "INVALID_REQUEST",
      "message": "Missing required calculation parameters",
      "code": 400
    }
    ```
    
2.  **Authentication Error**
    
    ```json
    {
      "error": "UNAUTHORIZED",
      "message": "Invalid or expired access token",
      "code": 401
    }
    ```
    

## [Integration Guide](#integration-guide)

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