Zinnia Illustration Generation API

openapi: 3.0.1
info:
  version: 3.5.3
  title: Illustration Generation
  description: Create and manage illustration requests
servers:
- url: https://dev.api.zinnia.io
  description: Development
tags:
- name: Illustration Engine
  description: API Endpoints for use by the internal illustration engines
- name: Term Life (TL) Illustrations
  description: Term Life product illustrations
- name: Indexed Universal Life (IUL) Illustrations
  description: Term Life product illustrations
- name: Whole Life (WL) Illustrations
  description: Whole Life product illustrations
- name: Hybrid-IUL-Term (HIT) Illustrations
  description: Hybrid-IUL/Term product illustrations
- name: Utility
  description: Utility operations
paths:
  /illustration/v3/illustration-request:
    post:
      operationId: create-illustration
      summary: Create an illustration
      description: Start an asynchronous illustration calculation
      parameters:
      - name: formats
        in: query
        description: what output formats should be generated and stored for retrieval
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Output-Format'
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calculation-Illustration'
      responses:
        '201':
          description: The request was created, the identifier for the request is returned.
          content:
            application/json:
              schema:
                type: object
                example:
                  requestId: abc123def
        '400':
          description: the request was malformed
        '500':
          description: a processing error occurred
      security:
      - Auth0: []
      tags:
      - Illustration Engine
  /illustration/v3/illustration-request/{id}:
    summary: manage a specific illustration request
    get:
      operationId: get-illustration
      summary: Get a specific illustration
      description: Get status of a specific asynchronous calculation request
      parameters:
      - in: path
        name: id
        description: the illustration request identifier for which status information is desired
        schema:
          type: string
        required: true
      - in: query
        name: format
        description: The output format for which information status information is desired. If not supplied will return status
          of all formats associated with the request identifier.
        schema:
          $ref: '#/components/schemas/Output-Format'
        required: false
      responses:
        '200':
          description: The request has been processed and results may be retrieved.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Output-Status'
                - type: string
                  description: Status of a single requested format, if only one format is requested
                  example: COMPLETE
        '202':
          description: The request has been accepted and is queued for processing.
        '400':
          description: The requested format is not supported.
        '404':
          description: The specified combination of request and format is not in the processing queue.
      security:
      - Auth0: []
      tags:
      - Illustration Engine
  /illustration/v3/illustration-request/{id}/results/{format}:
    summary: Operations on the results of a specific illustration request in a specific format
    description: Allows for manipulation of the results form a specific asynchronous illustration request
    get:
      operationId: get-illustration-result
      summary: Get a specific illustration result
      description: Retrieve the results for the specified illustration request in the specified format
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      - in: path
        name: format
        schema:
          $ref: '#/components/schemas/Output-Format'
        required: true
        description: The desired output format to retrieve.
      responses:
        '200':
          description: The content was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calculation-Illustration'
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: The requested format could not be found for the specified illustration.
        '415':
          description: The requested media type is not supported for the specified format.
        '500':
          description: Unexpected error encountered while trying to fetch response, OR response fetched successfully but contains
            calculation error messages
      security:
      - Auth0: []
      tags:
      - Illustration Engine
  /illustration/v3/illustration:
    post:
      operationId: illustration-for-immediate-processing
      summary: Illustration for immediate processing
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calculation-Illustration'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calculation-Illustration'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Illustration Engine
  /illustration/v3/version:
    get:
      operationId: get-version
      summary: Get API version
      description: Returns the current version of the illustration API
      responses:
        '200':
          description: Version information retrieved successfully
          content:
            application/json:
              schema:
                type: string
                description: The current API version
                example: 3.2.12
      tags:
      - Utility
  /illustration/v3/health:
    get:
      operationId: get-health
      summary: Health Check
      description: Returns 200
      responses:
        '200':
          description: Empty 200 to indicate API is healthy
      tags:
      - Utility
  /illustration/v3/term-life/new-business:
    post:
      operationId: illustration-for-new-term-life
      summary: Illustration for new term life
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-TL'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-TL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Term Life (TL) Illustrations
  /illustration/v3/term-life/new-business/{id}:
    get:
      operationId: get-illustration-for-new-term-life
      summary: Illustration for new term life
      description: Triggers an immediate calculation and returns the calculated results.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-TL'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-TL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Term Life (TL) Illustrations
  /illustration/v3/term-life/in-force/what-if:
    post:
      operationId: illustration-for-in-force-term-life
      summary: Illustration for in-force term life - what-if scenario
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-TL-Inforce-What-If'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-TL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred.
      security:
      - Auth0: []
      tags:
      - Term Life (TL) Illustrations
  /illustration/v3/term-life/in-force/what-if/{id}:
    get:
      operationId: get-illustration-for-in-force-term-life
      summary: Illustration for in-force term life - what-if scenario
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-TL-Inforce-What-If'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-TL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred.
      security:
      - Auth0: []
      tags:
      - Term Life (TL) Illustrations
  /illustration/v3/indexed-universal-life/new-business:
    post:
      operationId: illustration-for-new-indexed-universal-life
      summary: Illustration for new indexed universal life
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-IUL'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/indexed-universal-life/new-business/{id}:
    get:
      operationId: get-illustration-for-new-indexed-universal-life
      summary: Illustration for new Indexed Universal Life (IUL)
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-IUL'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/indexed-universal-life/in-force/what-if:
    post:
      operationId: illustration-for-in-force-indexed-universal-life
      summary: Illustration for in-force indexed universal life - what-if scenario
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-IUL-Inforce-What-If'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/indexed-universal-life/in-force/what-if/{id}:
    get:
      operationId: get-illustration-for-in-force-indexed-universal-life
      summary: Illustration for in-force Indexed Universal Life (IUL) what-if scenario
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-IUL-Inforce-What-If'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/whole-life/new-business:
    post:
      operationId: illustration-for-new-whole-life
      summary: Illustration for new whole life
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-WL'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-WL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Whole Life (WL) Illustrations
  /illustration/v3/whole-life/new-business/{id}:
    get:
      operationId: get-illustration-for-new-whole-life
      summary: Illustration for new whole life
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-WL'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-WL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Whole Life (WL) Illustrations
  /illustration/v3/indexed-universal-life/in-force/as-is:
    post:
      operationId: illustration-for-in-force-indexed-universal-life-as-is
      summary: Illustration for in-force indexed universal life - as-is scenario
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-IUL-Inforce-As-Is'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/indexed-universal-life/in-force/as-is/{id}:
    get:
      operationId: get-illustration-for-in-force-indexed-universal-life-as-is
      summary: Illustration for in-force Indexed Universal Life (IUL) as-is scenario
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-IUL-Inforce-As-Is'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-IUL'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Indexed Universal Life (IUL) Illustrations
  /illustration/v3/hybrid-iul-term/new-business:
    post:
      operationId: illustration-for-new-hybrid-iul-term
      summary: Illustration for new hybrid-iul-term
      description: Triggers an immediate calculation and returns the calculated results.
      requestBody:
        description: contains all the input data needed for processing the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Illustration-Inputs-HIT'
      responses:
        '200':
          description: the request was processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Illustration-Response-HIT'
        '400':
          description: The posted request was invalid for any reason.
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Hybrid-IUL-Term (HIT) Illustrations
  /illustration/v3/hybrid-iul-term/new-business/{id}:
    get:
      operationId: get-illustration-for-new-hybrid-iul-term
      summary: Illustration for new Hybrid-IUL/Term (HIT)
      description: Retrieves the calculated results for the specified illustration request.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: The unique identifier for the illustration request.
      responses:
        '200':
          description: the request was processed and results may be retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    $ref: '#/components/schemas/Illustration-Inputs-HIT'
                  response:
                    $ref: '#/components/schemas/Illustration-Response-HIT'
        '400':
          description: The posted request was invalid for any reason.
        '404':
          description: Unable to find illustration by provided id
        '500':
          description: An unexpected processing error occurred, OR the request was processed successfully but contains calculation
            error messages.
      security:
      - Auth0: []
      tags:
      - Hybrid-IUL-Term (HIT) Illustrations
  /illustration/v3/utility/calculateAge:
    post:
      operationId: calculate-age
      summary: Calculate age
      description: Calculates age based on date of birth and as-of date using specified calculation method
      requestBody:
        description: Age calculation request containing date of birth, as-of date, and calculation method
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Age-Calculation-Request'
      responses:
        '200':
          description: Age calculation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Age-Calculation-Response'
        '400':
          description: The request was malformed
        '500':
          description: An unexpected processing error occurred
      security:
      - Auth0: []
      tags:
      - Utility
components:
  schemas:
    Age-Calculation-Request:
      type: object
      required:
      - dateOfBirth
      - asOfDate
      - calculationMethod
      properties:
        dateOfBirth:
          type: string
          format: date
          description: Date of birth in ISO-8601 format
          example: '1990-08-25'
        asOfDate:
          type: string
          format: date
          description: As-of date in ISO-8601 format
          example: '2025-08-25'
        calculationMethod:
          $ref: '#/components/schemas/Age-Calculation-Method'
    Age-Calculation-Response:
      type: object
      properties:
        age:
          type: integer
          description: Calculated age
          example: 35
        monthsSinceLastBirthday:
          type: integer
          description: Number of months since last birthday
          example: 0
    Age-Calculation-Method:
      type: string
      enum:
      - AGE_LAST
      - AGE_NEAREST
      description: Age calculation method - AGE_LAST for age at last birthday, AGE_NEAREST for age at nearest birthday
      example: AGE_LAST
    Date-Field:
      type: string
      format: date
      pattern: ([0-9]{4})-([0-9]{2})-([0-9]{2})
      description: Date (with pattern "yyyy-mm-dd")
      example: '2025-05-13'
    Illustration-Inputs-Base:
      title: Illustration Request
      description: Fundamental Illustration request schema. See the schema for a specific product
      properties:
        calculationType:
          type: string
          description: Type of calculation. Only SINGLE_ILLUSTRATION triggers a PDF to be generated.
          example: QUICK_QUOTE
          enum:
          - QUICK_QUOTE
          - SINGLE_ILLUSTRATION
          - AGGREGATE_ILLUSTRATION
          - COMPOSITE_ILLUSTRATION
          - POLICY_PAGE_PROJECTION
          - INITIAL_QUOTE
        source:
          type: string
          description: Source of the request
          example: ZINNIA
        illustrationRequestDate:
          $ref: '#/components/schemas/Date-Field'
        reports:
          type: object
          properties:
            internalRateOfReturnOn:
              type: boolean
              description: Internal rate of return
              example: true
            annualChargesOn:
              type: boolean
              description: Annual charges
              example: true
            annualChargesYears:
              type: number
              description: Annual charges years
              format: integer
              example: 10
            monthlyChargesOn:
              type: boolean
              description: Monthly charges
              example: true
            monthlyChargesYears:
              type: number
              format: integer
              description: Monthly charges years
              example: 10
            marketingPagesOn:
              type: boolean
              description: Whether to produce marketing pages
              example: true
            costDetailsReportOn:
              type: boolean
              description: Whether to produce the cost details report
              example: true
            inputSummaryOn:
              type: boolean
              description: Whether to produce the input summary
              example: true
      required:
      - calculationType
      - illustrationRequestDate
    Illustration-Inputs-Projection-Base:
      title: Projection Base
      description: Base for projection scenarios
      allOf:
      - $ref: '#/components/schemas/Illustration-Inputs-Base'
      - type: object
        properties:
          coverages:
            $ref: '#/components/schemas/Coverage-Collection-V4'
          parties:
            type: array
            description: Must have at least one party representing the Insured participant
            items:
              anyOf:
              - $ref: '#/components/schemas/Non-Insured-Party'
              - $ref: '#/components/schemas/Insured'
            minItems: 1
            uniqueItems: true
          options:
            $ref: '#/components/schemas/Options-Base'
        required:
        - coverages
        - parties
    Illustration-Inputs-New-Business-Base:
      title: New Business Base
      description: Properties for new business scenarios
      type: object
      properties:
        jurisdiction:
          type: string
          description: US state code.https://en.wikipedia.org/wiki/ISO_3166-2:US
          enum:
          - AK
          - AL
          - AR
          - AS
          - AZ
          - CA
          - CO
          - CT
          - DC
          - DE
          - FL
          - GA
          - GU
          - HI
          - IA
          - ID
          - IL
          - IN
          - KS
          - KY
          - LA
          - MA
          - MD
          - ME
          - MI
          - MN
          - MO
          - MP
          - MS
          - MT
          - NC
          - ND
          - NE
          - NH
          - NJ
          - NM
          - NV
          - NY
          - OH
          - OK
          - OR
          - PA
          - PR
          - RI
          - SC
          - SD
          - TN
          - TX
          - UM
          - UT
          - VA
          - VI
          - VT
          - WA
          - WI
          - WV
          - WY
        planCode:
          type: string
          description: Plan code
          example: EG123
      required:
      - jurisdiction
      - planCode
    Illustration-Inputs-TL:
      title: Illustration Request for Term Life
      description: Illustration Request for Term Life product
      allOf:
      - $ref: '#/components/schemas/Illustration-Inputs-Projection-Base'
      - $ref: '#/components/schemas/Illustration-Inputs-New-Business-Base'
    Illustration-Inputs-TL-Inforce-What-If:
      title: Illustration Request for Term Life - Inforce What-If
      description: Illustration Request for Term Life product - Inforce What-If scenario
      allOf:
      - $ref: '#/components/schemas/Illustration-Inputs-TL'
      - $ref: '#/components/schemas/Illustration-Inputs-Inforce-Base'
    Illustration-Inputs-WL:
      title: Illustration Request for Whole Life
      description: Illustration Request for Whole Life product
      allOf:
      - $ref: '#/components/schemas/Illustration-Inputs-Projection-Base'
      - $ref: '#/components/schemas/Illustration-Inputs-New-Business-Base'
      - type: object
        properties:
          conversion:
            $ref: '#/components/schemas/Conversion'
          surplusDistribution:
            type: object
            description: Surplus distribution configuration for whole life policy
            properties:
              surplusDistributionOption:
                $ref: '#/components/schemas/Schedule-SurplusDistributionOption'
              excessSurplusDistributionOption:
                type: string
                description: Excess surplus distribution handling option
                example: CASH
                enum:
                - CASH
                - PAID_UP_ADDITION
            required:
            - surplusDistributionOption
          distributions:
            $ref: '#/components/schemas/Distributions'
        required:
        - surplusDistribution
    IUL-Shared-Properties:
      title: IUL Shared Properties
      description: Properties shared between IUL and HIT products
      type: object
      properties:
        conversion:
          $ref: '#/components/schemas/Conversion'
        lumpSumDeposits:
          description: Additional one-time payments that take place at specified points in time
          type: array
          items:
            type: object
            required:
            - amount
            properties:
              amount:
                description: lump sum deposit amount
                type: number
                format: double
                example: 100000
            

# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zinnia/refs/heads/main/openapi/zinnia-illustration-openapi.yml