Wholesale Quote Lifecycle

flowchart LR
    A["POST /wholesale/quotes"] -->|"Creates annual quote"| B["Quote Created"]
    B -->|"Partner confirms"| C["POST /quotes/{quoteId}/purchase"]
    B -->|"Partner declines"| D["POST /quotes/{quoteId}/reject"]
    B -->|"7 days pass"| E["Quote Expired"]
    C -->|"Policy activated"| F["Active Annual Policy"]
    F -->|"View performance"| G["GET /policies/{policyId}/annual-summary"]

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

What This Endpoint Does

This is the B2B endpoint for annual parametric insurance products. It creates quotes with fixed daily payouts over a 12-month coverage period, designed for wholesale partners embedding annual weather protection into their offerings.

1. Validates Product Type: Accepts annual or annual_cat policy types only
2. Calculates Annual Coverage: Builds a month-by-month trigger schedule based on location and weather data
3. Generates Pricing: Returns a quote with fixed daily payout structure and premium breakdown
4. Returns Consistent Format: Uses the same response structure as POST /quotes for seamless integration

Note: The B2C endpoint POST /quotes does not accept annual products. Sending policyType: "annual" or "annual_cat" to POST /quotes returns a validation error directing you to this endpoint.

When to Use This Endpoint

Use POST /wholesale/quotes when:

• Creating annual parametric coverage for a wholesale or B2B partner
• The partner needs fixed daily payouts rather than event-based coverage
• You are quoting annual (standard monthly cap) or annual_cat (catastrophe with gap days) products
• The coverage period is a full 12 months starting from the 1st of a month

Use POST /quotes instead when:

• Creating short-term weather protection for individual consumers (B2C)
• The policy type is weather (standard rainfall trigger)
• Coverage is for a specific date range (not a full year)

Policy Types

This endpoint supports two annual product types. Each routes to a different pricing engine internally.

Request Parameters Explained

policyType (required): Must be "annual" or "annual_cat". This determines which pricing engine and parameter set is used.

coverage.fixedPayoutPerDay (required): The dollar amount paid per trigger day. Must be a positive number. This is the core pricing input for all wholesale products.

coverage.startDate: The first day of the 12-month coverage period. Must be the 1st of a month (e.g., "2026-07-01"). The end date is automatically calculated as startDate + 12 months.

Annual-Specific Parameters

coverage.monthlyCapDays (annual only): Maximum number of payout days in any single month. Defaults to 12 if not provided. Use this to limit monthly exposure.

coverage.annualDeductibleDays (annual only): Number of trigger days that must occur before any payouts begin. Defaults to 0 (no deductible). Setting this to 5, for example, means the first 5 trigger days in the year produce no payout.

Annual CAT-Specific Parameters

coverage.gapDays (annual_cat only): Minimum number of days between qualifying catastrophic events. Used to separate distinct weather incidents.

coverage.annualCapDays (annual_cat only): Maximum total payout days across the entire 12-month period.

B2B Customer Fields

In addition to the standard customer fields (email, firstName, lastName, phone, companyName, memberNumber), wholesale quotes support:

customer.companyId: The partner's internal company identifier for the insured business.

customer.businessNumber: Business registration number (e.g., ABN in Australia, NZBN in New Zealand).

Shared Parameters

The following parameters work identically to POST /quotes:

• experienceDetails (name, type, location with suburb, state, country, coordinates)
• customer (optional at quote time, required at purchase)
• onBehalfOf (distributorCode, distributorName, reference) for network provider tracking
• options.partnerQuoteId for your internal tracking reference

Understanding the Response

The response follows the same structure as POST /quotes, with additional fields for annual products:

quote.policy_type: Returns "annual" or "annual_cat" confirming the product type.

quote.annual: An object containing the annual coverage breakdown:

• monthly_schedule: Array of 12 entries, one per month, each containing:
  • Month and year
  • Trigger threshold for that month
  • Number of covered days
• covered_days: Total number of days eligible for payout across the year
• annual_deductible_days: The deductible applied (from your request or default)
• fixed_payout_per_day: The daily payout amount (echoed from your request)

quote.pricing_options[]: Array of coverage options, each with:

• quote_id -- use this to purchase
• premium breakdown (total, base, tax, daily rate)
• total_coverage and daily_coverage amounts

quote.on_behalf_of: Echoed distributor tracking information (if provided in the request).

Error Handling

Validation Errors (400)

Business Logic Errors (422)

Server Errors (500)

Best Practices

1. Choose the right product type: Use annual for general ongoing protection with monthly caps. Use annual_cat for catastrophic event coverage with gap-day separation.
2. Set appropriate daily payouts: The fixedPayoutPerDay directly determines the premium. Start with representative values and adjust based on the partner's risk appetite.
3. Start dates must be the 1st: Annual coverage always begins on the first of a month. Plan quote creation accordingly.
4. Use the x-api-channel header: Set this to identify your integration channel (e.g., "partner-portal", "api-direct"). Defaults to "external".
5. Include onBehalfOf for distributors: When creating quotes on behalf of sub-distributors in your network, always populate the distributor tracking fields for accurate reporting.
6. Include B2B customer fields: For business customers, provide companyId and businessNumber at quote time to streamline the purchase flow.
7. Use X-Request-Id for tracing: Include a unique request ID header for debugging and support inquiries.

Next Steps

After creating a wholesale quote:

1. Review the pricing options and annual coverage breakdown
2. Use POST /quotes/{quoteId}/purchase to convert the selected option into an active annual policy
3. Use GET /policies/{policyId}/annual-summary to monitor monthly performance and payout status

Note: Annual policies cannot currently be modified or cancelled via the API. Contact support for changes to active annual policies.