Purchase Flow

What This Endpoint Does

1. Validates Quote: Ensures the quote is still valid and not expired
2. Creates Policy: Generates a unique policy number and activates coverage
3. Stores Customer Data: Securely saves customer information for claims
4. Returns Policy: Provides complete policy details including payment breakdown

When to Use This Endpoint

Call this endpoint when:

• Customer has selected their preferred coverage tier from the quote
• Payment has been successfully processed in your system
• You have collected all required customer information
• Customer has agreed to the insurance terms

Important: Quote ID Selection

Use the quote_id from one of the pricing_options in your quote response, NOT the parent quote object.

1. Create quote → Receive response with pricing_options
2. Customer selects an option (e.g., "Full Coverage")
3. Extract that option's quote_id
4. Use that quote_id in: `POST /quotes/{quote_id}/purchase`

Request Parameters

Understanding the Response

policy object contains:

coverage object:

protection object:

payment object:

is_modification: Boolean indicating if this policy resulted from a modification.

Error Handling

Idempotency

Include X-Request-Id header for safe retries:

• System caches responses for 7 days (168 hours)
• Retrying with same request-id returns original policy
• Check X-Idempotent-Replayed: true header to detect cached responses
• Only 2xx and 4xx responses are cached — 5xx errors are always retryable
• The request body is hashed — sending a different body with the same key returns an error
• Always use idempotency in production for network resilience

Best Practices

1. Process payment first: Only call this endpoint after payment succeeds
2. Always use idempotency: Include X-Request-Id on every purchase request
3. Store policy_id: Required for future modify/cancel operations
4. Include bookingReference: Essential for reconciliation
5. Send confirmation: Email policy_number to customer immediately

Next Steps

After successful purchase:

1. Send policy confirmation email with policy_number
2. Store policy_id linked to your booking
3. Use GET /policies/{id} to retrieve policy status
4. Use POST /policies/{id}/modify if customer changes dates
5. Use POST /policies/{id}/cancel if booking is cancelled