Zinnia Policy Service API

Table of Contents

• What is the Zinnia Policy Service API?
• Core Capabilities
• API Reference
  • Get Policy Details
  • Get Policy Versions
  • One-Time Premium
• Error Handling
• Troubleshooting Common Error Scenarios
• Support and Resources

What is the Zinnia Policy Service API?

The Zinnia Policy Service API is a comprehensive, enterprise-grade solution designed to modernize and streamline insurance policy management. It serves as a central hub for all policy-related operations throughout the entire policy lifecycle, from creation to claims processing.

Core Capabilities

• Policy Administration: Create, activate, update, and manage policies, including version control and document management.
• Financial Management: Process premiums, allocate and transfer funds, manage loans, and process withdrawals.
• Party Management: Manage policyholder information, beneficiary administration, agent and administrator access control, and contact information updates.
• Claims Processing: Initiate and process death claims, calculate benefits, disburse payments, and verify documents.
• Reporting and Analytics: View transaction history, policy performance metrics, audit trails, and compliance reporting.

API Reference

Get Policy Details

/policy/v1/policies/{planCode}/{policyNumber}

Method

GET

Purpose:
Retrieve detailed information about a specific policy using a plan code and policy number.

Parameters:

These values must be correctly formatted and valid for the request to succeed. If either is missing or invalid, the API will return a 400 or 404 error.

Returns:
This endpoint returns a JSON response containing the result of the request, including whether it was successful and detailed information about the requested policy. The response is consistent and structured to support reliable parsing, integration, and auditing across systems.

Get Policy Versions

/policy/v1/policies/{planCode}/{policyNumber}/versions

Method

GET

Purpose:
Retrieve the version history of a specific policy, with optional filtering and pagination support.

Parameters:

Ensure path parameters are provided and valid. Query parameters are optional but can be used to narrow the results or limit payload size. Invalid path values will result in a 400 or 404 error, while invalid query parameters may also result in a 400.

Returns:
This endpoint returns a JSON response listing historical versions of the specified policy. The results can be filtered and limited, and are formatted to support easy client-side parsing, pagination, and auditing.

One-Time Premium

/policy/v1/policies/{planCode}/{policyNumber}/onetimepremium/quote

Method

POST

Purpose:
Get a quote for a one-time premium payment, retrieving the calculated premium amount for a single payment.

Parameters:

These values must be correctly formatted and valid for the request to succeed. If either is missing or invalid, the API will return a 400 or 404 error.

Body:

Example Request:

{
  "request": {
    "correlationId": "657b717b7dcf554abf9ef067",
    "policyDetails": {
      "planCode": "ZLIC001",
      "policyNumber": "POL123456789",
      "effectiveDate": "2024-02-14"
    },
    "premium": {
      "amount": 100000.00,
      "paymentMethod": {
        "type": "ACH",
        "accountDetails": {
          "accountNumber": "****1234",
          "routingNumber": "****5678",
          "accountType": "CHECKING",
          "accountHolderName": "John Doe"
        }
      }
    }
  }
}

Returns:
This endpoint returns a JSON response listing information generated about a one-time premium payment quote. The response includes information about the policy and the quote amount, and whether the call was successful or not.

Example Response:

{
  "status": "success",
  "data": {
    "correlationId": "657b717b7dcf554abf9ef067",
    "transactionStatus": "COMPLETED",
    "policyDetails": {
      "policyNumber": "POL123456789",
      "status": "ACTIVE",
      "effectiveDate": "2024-02-14",
      "initialPremium": {
        "amount": 100000.00,
        "processedDate": "2024-02-14",
        "paymentStatus": "PROCESSED"
      }
    }
  }
}

Error Handling

Standard Error Format

{
  "status": "failure",
  "validationResult": [
    {
      "code": "ERROR_001",
      "message": "Invalid request parameters",
      "severity": "ERROR",
      "details": {
        "field": "premium.amount",
        "constraint": "Must be greater than minimum premium of $10,000",
        "providedValue": 5000
      }
    }
  ]
}

Troubleshooting Common Error Scenarios

When interacting with our APIs, you may occasionally receive errors. Below are the most common categories, typical HTTP status codes, example error messages, and guidance on how to interpret or adjust your requests.

Validation Errors

HTTP Status Codes: 400 Bad Request

These occur when the request is well-formed but contains invalid or missing data.

Example Messages:

• 400 Bad Request – "email must be a valid email address"
• 400 Bad Request – "startDate is required"

What This Means:

• The request body or query parameters didn't meet expected formats or business rules.
• Required fields may be missing, or fields may have unexpected values.

What to Check:

• Are all required fields present?
• Are values in the expected formats (e.g., ISO 8601 for dates)?
• Do any fields violate constraints (e.g., negative amounts, invalid enum values)?

Authentication & Authorization Errors

HTTP Status Codes: 401 Unauthorized, 403 Forbidden, 429 Too Many Requests

These indicate issues with access control, tokens, or rate limits.

Example Messages:

• 401 Unauthorized – "Invalid or expired token"
• 403 Forbidden – "You do not have access to this resource"
• 429 Too Many Requests – "Rate limit exceeded. Try again in 60 seconds."

What This Means:

• 401 means the request is missing valid authentication credentials.
• 403 means the credentials are valid, but access to the resource is not allowed.
• 429 means too many requests have been made in a short period.

What to Check:

• Ensure you're including a valid Authorization header.
• Confirm that your token hasn't expired.
• Make sure your account or client has access to the requested endpoint.
• If rate limited, wait and retry after the period indicated in the Retry-After header.

System & Infrastructure Errors

HTTP Status Codes: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout

These are typically issues on our side or between services.

Example Messages:

• 500 Internal Server Error – "Unexpected exception occurred"
• 502 Bad Gateway – "Failed to connect to external service"
• 503 Service Unavailable – "The service is currently undergoing maintenance"
• 504 Gateway Timeout – "Upstream service did not respond in time"

What This Means:

• There may be temporary service degradation or outages.
• Your request reached us but couldn't be fulfilled due to system issues.

What to Do:

• These errors are usually not caused by your request.
• Retrying the request after a short delay may help.
• If the issue persists, check our status page or contact support.

General Guidelines for Error Responses

• Consistent format: Error responses generally follow this structure:

{
    "error": {
        "code": "string",
        "message": "string",
        "details": [
            {
                "field": "string",
                "message": "string"
            }
        ]
    }
}

• Status codes are meaningful:
  • 4xx codes typically mean something is wrong with the request.
  • 5xx codes mean the issue is on the server side.
• Retry behavior:
  • Do not retry on 400, 401, or 403 unless the request has been corrected.
  • You may retry on 429, 500, 502, 503, and 504 using exponential backoff.

Support and Resources

Documentation

• API Reference
• Integration Guide
• Best Practices
• Security Guidelines

Support Channels

• Technical Support: support@zinnia.com
• Developer Forum: forum.zinnia.com
• Status Page: status.zinnia.com

Tools and SDKs

• Python SDK
• Java SDK
• .NET SDK
• API Postman Collection