Search, Retrieve, and Display Policy Information

Use this guide to reproduce the workflow described in the BriteCore Help Center article for retrieving and displaying policy information. It covers the policy APIs that power list views, policy detail pages, and historical snapshots so you can wire them into back-office tools, portals, or data pipelines.

Overview

• Audience: Engineers, analysts, and technical support staff who surface policy data outside of the native BriteCore UI.
• What you get: End-to-end instructions plus request/response examples for the search, retrieve, and display APIs under /api/v2/policies.
• When to use it: Any time you need to locate a policy, pull its summary, and render line-item or coverage details for a specific effective date.

Before You Begin

• Environment: Identify the correct tenant hostname (for example, https://demo-carrier.britecorepro.com).
• Authentication: Supply a valid session cookie, OAuth bearer token, or api_key (all samples below use an api_key placeholder).
• Permissions: Users typically need britecore/policies/* capabilities that cover search, retrieval, and snapshot operations.
• Data hygiene: Confirm the policy numbers, UUIDs, and effective dates you plan to query. Snapshot lookups are date-sensitive.

Workflow Summary

Endpoint Details

1. Search for policies — POST /api/v2/policies/search

Returns a paginated result set filtered by policy metadata. Keys such as statuses, policy_types, revision_states, and review_states accept arrays. sort_obj controls ordering (field + order).

⚠️ review_states only works when the policies.show-review-state-column setting is enabled. If it is disabled, the API responds with a validation error instead of silently ignoring the filter.

Example request

{
  "api_key": "{{apiKey}}",
  "search_string": "Smith",
  "statuses": ["Active", "Submitted"],
  "policy_types": ["Homeowners"],
  "revision_states": ["committed"],
  "review_states": ["APPROVED_BY_UW"],
  "sort_obj": {"field": "effective_date", "order": "desc"},
  "current_page": 1,
  "page_size": 50
}

Example response (abridged)

{
  "success": true,
  "data": {
    "activePage": 1,
    "maxPages": 12,
    "records": [
      {
        "policyId": "0c214a22-0475-4c63-9e17-1bde470a5b35",
        "policyNumber": "HO-1023456-01",
        "namedInsured": "Jordan Smith",
        "policyType": "Homeowners",
        "status": "Active",
        "effectiveDate": "2024-06-01",
        "expirationDate": "2025-06-01",
        "reviewState": "APPROVED_BY_UW",
        "flag": "white",
        "isGen3": false
      }
    ]
  }
}

Notes

• The API normalizes internal keys returned by retrievePolicies. For instance, policyNumber is remapped from policyId, while policyId becomes the database UUID (dbPolicyId).
• Paginate by adjusting current_page and page_size; the response surfaces maxPages so you can stop requesting new pages when you reach the end.

2. Retrieve the policy summary — POST /api/v2/policies/retrieve_policy

Use either policy_id (UUID) or policy_number. Optionally pass revision_state (defaults to committed) or revision_id when you need a specific revision.

Example request

{
  "api_key": "{{apiKey}}",
  "policy_number": "HO-1023456-01",
  "revision_state": "committed"
}

Response highlights

• id, policy_number, previous_policy_numbers
• Policy flags (active, rewritten, flag)
• Submission contacts (submit_bound, emails, names)
• active_revision (builder status, underwriting state, rating totals)
• active_policy_term plus next_policy_term when present
• policy_contacts bucketed by contact role
• britecore_claims, system_tags, and can_make_payment

This call powers the summary pane for a policy detail page. Dates are normalized to UTC strings so they align with event logs.

3. Retrieve policy terms — POST /api/v2/policies/retrieve_policy_terms

Returns every term (sorted by effective date descending) along with its revisions. Pass policy_id or policy_number.

Example response fragment

[
  {
    "id": "9e3c9a0a-1d5e-4e71-b864-baa7e7ddc461",
    "policy_id": "0c214a22-0475-4c63-9e17-1bde470a5b35",
    "effective_date": "2024-06-01",
    "expiration_date": "2025-06-01",
    "term_length": 12,
    "term_type": "Annual",
    "renewal_status": "Pending",
    "auto_payment_method_id": null,
    "revisions": [
      {
        "id": "7abcc37a-5797-4e33-9e8a-9772fb9f2784",
        "revision_state": "committed",
        "policy_status": "Active",
        "written_premium": 1425.00,
        "annual_premium": 1425.00,
        "grant_mortgagee_extension": false,
        "underwriting_questions": [],
        "builder_pending": false
      }
    ]
  }
]

Use the revision IDs from this payload to drill further into specific versions or to drive UI selectors (for example, a revision dropdown).

4. Retrieve a point-in-time snapshot — POST /api/v2/policies/retrieve_policy_snapshot

Takes policy_number and snapshot_date (YYYY-MM-DD) and returns the serialized quote payload (contacts, policy term, revision, and coverages) as it existed on that date. Behind the scenes it calls QuoteService.get_policy_snapshot and serializes the result with CreateFullQuoteResponseModel, so the response aligns with what downstream services expect from a full quote.

Example request

{
  "api_key": "{{apiKey}}",
  "policy_number": "HO-1023456-01",
  "snapshot_date": "2024-09-15"
}

Use cases

• Rendering declarations or timeline comparisons.
• Feeding external reporting or downstream rating audits with the exact data state at a specific point in time.

Procedure

1. Search for the policy. Call /api/v2/policies/search with the filters you need. Capture the policyId (UUID) and policyNumber from the record you plan to inspect.
2. Retrieve the summary. Pass the identifier into /api/v2/policies/retrieve_policy to obtain the active term, revision metadata, tags, and contact blocks that underpin UI summary widgets.
3. Present the term timeline. Invoke /api/v2/policies/retrieve_policy_terms to populate term cards, renewal banners, or revision pickers.
4. Display detailed data. When an end user selects a term/date, call /api/v2/policies/retrieve_policy_snapshot with the policy_number and the appropriate snapshot_date. Bind the resulting coverage items, questions, limits, and contacts directly to your UI or document template.

Tip: Cache the search and policy summary responses (Steps 1–2) for the duration of a user session. Snapshots should generally remain uncached so that date-specific changes are always fetched fresh.

Troubleshooting and Tips

• Review-state filtering: If you receive Showing review state field is currently disabled, enable policies.show-review-state-column in Settings or remove review_states from the payload.
• Policy identifiers: policyId (UUID) and policyNumber (human-friendly number) swap meanings between the search response and other APIs. Always persist both so you can call whichever endpoint needs a UUID vs. a policy number.
• Snapshot dates: Use YYYY-MM-DD. Requests without snapshot_date return a 400-level validation error.
• Throughput: All endpoints are POSTs; batch pagination and concurrency thoughtfully to avoid hammering the search index.

Related APIs

• POST /api/v2/policies/retrieve_revision_details — returns the full revision payload when you already know the revision_id.
• POST /api/v2/policies/retrieve_policy_change_logs — audit trail of changes if you need to display deltas alongside snapshots.
• POST /api/v2/policies/search with sort_obj variations — useful for default dashboards (e.g., newest effective date first).

Leverage these adjunct endpoints when you need deeper drilldowns beyond the baseline search/retrieve/display flow described above.