Lookup Paths

flowchart LR
    A["GET /policies"] --> B{"Query parameter?"}
    B -->|"?quote_id=uuid"| C["Direct policy table<br/>lookup by quote_id"]
    B -->|"?payment_reference=ref"| D["Transactions table →<br/>Policy table join"]
    B -->|"Neither"| E["400 MISSING_PARAMETER"]
    C --> F{"Found?"}
    D --> F
    F -->|"Yes"| G["200 + policy summary"]
    F -->|"No"| H["200 + policy: null"]

    style A fill:#e3f2fd
    style G fill:#e8f5e9
    style H fill:#fff3e0
    style E fill:#fce4ec

What This Endpoint Does

1. Searches for Policy: Finds a policy using quote_id or payment_reference
2. Returns Summary: Provides basic policy info if found
3. Handles Not Found: Returns null policy if no match (not an error)

When to Use This Endpoint

• Post-Purchase Lookup: Find policy_id after purchase using payment_reference
• Quote Conversion Check: Verify if a quote was converted to a policy
• Reconciliation: Match payments to policies

Query Parameters

Provide exactly one parameter. The quote_id parameter does a direct policy lookup, while payment_reference searches via the transactions table. If both are provided, quote_id takes precedence.

Understanding the Response

policy object (null if not found):

Response Behaviour

• Policy found: Returns policy summary with 200 status
• Policy not found: Returns "policy": null with 200 status (not an error)
• Missing parameters: Returns 400 error

Error Handling

Best Practices

1. Use for lookup only: For full policy details, use GET /policies/{policyId}
2. Check for null: Policy being null is a valid response, not an error
3. Prefer quote_id: More reliable than payment_reference for exact matches