Quote-to-Policy Lifecycle

flowchart LR
    A["POST /quotes"] -->|"Creates pricing options"| B["Quote Created"]
    B -->|"Customer selects tier"| C["POST /quotes/{id}/purchase"]
    B -->|"Customer declines"| D["POST /quotes/{id}/reject"]
    B -->|"3 hours pass"| E["Quote Expired"]
    C -->|"Policy activated"| F["Active Policy"]
    F -->|"Dates change"| G["POST /policies/{id}/modify"]
    F -->|"Booking cancelled"| H["POST /policies/{id}/cancel"]
    G -->|"New quote generated"| B

    style A fill:#e3f2fd
    style C fill:#e8f5e9
    style F fill:#e8f5e9
    style D fill:#fce4ec
    style E fill:#fff3e0
    style H fill:#fce4ec

What This Endpoint Does

1. Analyses Location: Finds the nearest weather station to your specified coordinates
2. Calculates Risk: Uses historical weather data to assess rainfall probability
3. Generates Options: Returns up to 3 pricing tiers (typically 50%, 75%, and 100% payout levels)
4. Provides Transparency: Shows weather station details, trigger values, and premium breakdown

When to Use This Endpoint

Call this endpoint when:

• A customer is browsing your offerings and wants to see insurance pricing
• You need to show insurance costs during the booking flow
• A customer changes their dates/location and needs updated pricing
• You want to pre-calculate insurance options for your inventory

Request Parameters Explained

experienceDetails.type: The category of activity being insured

• camping: Outdoor camping and caravan parks
• hiking: Hiking trails and outdoor adventures
• event: Outdoor events, festivals, concerts
• sports: Sporting events and activities
• experience: Tours, experiences, and activities
• accommodation: Hotels, resorts, glamping

experienceDetails.location.coordinates: The exact location being insured

• We'll find the nearest official weather station (typically within 50km)
• The weather station distance affects pricing - closer stations may have better rates
• Coordinates should be accurate to ensure proper coverage

coverage.startDate & endDate: When the insurance is active

• Must be in YYYY-MM-DD format (e.g., "2025-03-15")
• Start date cannot be in the past
• Both dates must be within 12 months from today
• End date must be after start date
• Coverage includes both start and end dates (inclusive)

coverage.exposureAmount: The total booking/revenue value to protect

• This is the maximum potential payout across all covered days
• Should represent the actual financial risk (booking value, lost revenue, etc.)
• Subject to minimum and maximum limits (contact support for current limits)
• Currency is automatically determined by the location country

options.partnerQuoteId (optional): Your internal tracking reference

• Use this to link the quote to your booking system
• Helps with reconciliation and reporting
• Will be included in policy responses for easy matching
• Maximum 100 characters

Understanding the Response

The response includes:

quotes_generated: Number of pricing options (typically 3)

expires_at: When this quote expires (typically 3 hours from creation)

• After expiration, you'll need to create a new quote
• Ensures pricing reflects current weather conditions and risk

pricing_options[]: Array of coverage tiers

• Each option has a unique quote_id - use this to purchase
• payout_percentage: How much of the coverage amount is paid (50%, 75%, or 100%)
• total_coverage: Maximum payout for the entire period
• daily_coverage: Maximum payout per day
• premium: What the customer pays for this option
• is_voucher_option: Whether this option uses voucher payout (discount available)
• voucher_discount_amount: Premium discount when selecting voucher payout
• voucher_display_name: Display name for the voucher option

weather_protection: Details about the trigger mechanism

• trigger_value: Rainfall amount in millimeters that activates payout
• duration_hours: Time window for measuring rainfall (usually 24 hours)
• weather_station: The official station monitoring rainfall for this policy

Date Restrictions (Important!)

12-Month Policy Creation Window

• All coverage dates must fall within 12 months from today
• This ensures we have reliable weather data for accurate pricing
• If you need coverage beyond 12 months, create a new quote closer to the date

Why this restriction exists:

• Weather patterns change over time
• Seasonal data becomes more accurate closer to the coverage period
• Prevents stale pricing that doesn't reflect current conditions

Example scenarios:

• Today is January 15, 2025
• Valid: Coverage from June 1-5, 2025 (5 months away)
• Valid: Coverage from January 10-14, 2026 (12 months away)
• Invalid: Coverage from February 1-5, 2026 (12.5 months away)

Pricing and Premium Breakdown

Each pricing option includes a detailed premium breakdown:

• total_premium: The amount the customer pays (includes all taxes)
• base_premium: The insurance cost before taxes
• total_tax: Sum of all applicable taxes
• tax_breakdown: Individual tax components (e.g., GST, stamp duty)
• daily_rate: Cost per day of coverage

Taxes are automatically calculated based on the location's jurisdiction.

Common Use Cases

Scenario: Camping Booking Flow

1. Customer selects dates: March 15-18, 2025
2. Location: Sydney Tourist Park (-33.8727, 151.2057)
3. Booking value: $500
4. You call this endpoint to get quote options
5. Display the pricing tiers to customer (50%, 75%, 100% payout)
6. Customer selects preferred option (e.g., 100% coverage)

Error Handling

The endpoint validates all inputs before generating quotes. Common errors:

Validation Errors (400)

• Invalid date format (must be YYYY-MM-DD)
• Missing required fields
• Invalid coordinates (outside valid ranges)
• Invalid event type

Business Logic Errors (422)

• Dates exceed 12-month limit
• Start date in the past
• End date before start date
• Exposure amount outside limits
• No weather stations found near location
• Location not supported for coverage
• Risk too high for coverage

Performance and Limits

• Response Time: Typically 800ms
• Rate Limiting: Contact support for current limits
• Concurrent Requests: Supported, each request is independent
• Quote Storage: Quotes are stored and retrievable via GET /quotes/{quote_id}

Best Practices

1. Show All Options: Present all pricing tiers to customers for transparency
2. Explain Payout Levels: Help customers understand 50% vs 75% vs 100% coverage
3. Display Weather Station: Show the weather station name and distance to build trust
4. Handle Errors Gracefully: Provide clear feedback if coverage isn't available
5. Use Partner Quote ID: Always include your booking reference for tracking
6. Cache Wisely: Quotes are valid for 3 hours - don't create duplicates unnecessarily
7. Test in Sandbox: Always test with different locations and dates before production

Next Steps

After creating a quote:

1. Display the pricing options to your customer
2. When customer selects an option, use POST /quotes/{quote_id}/purchase to create the policy
3. Store the quote_id for the selected option
4. Complete payment processing in your system
5. Call the purchase endpoint with customer details and payment confirmation

Request ID Tracking

Include an X-Request-Id header for request tracing and debugging:

• Each response includes the X-Request-Id header (your value or auto-generated)
• Use this to correlate requests with support inquiries
• Recommended format: UUID or req-{timestamp}-{random}

Note: Idempotency (duplicate prevention) is supported on the purchase and cancel endpoints, not on quote creation. Creating a new quote with the same parameters will generate a new quote each time.