BriteCore Lines Product Definition APIs

BriteCore Lines gives administrators a modeling workspace for the entire product definition: effective dates, state-by-state availability, line hierarchies, policy types, rating grids, underwriting rules, and forms. The /api/v2/lines/* family exposes that product definition through a stateless API that external systems (rating services, configuration portals, migration utilities) can consume.

This guide modernizes the legacy Retrieve product definition article for external developers. It explains how to traverse the Lines data model, which endpoints to call, and how to interpret the deeply nested response payloads.

Authentication and Environment

• Base URL: https://{tenant}.britecore.com (match your tenant cluster).
• Authentication: All examples assume an api_key that authorizes Lines administration permissions. Include it in the JSON body of POST calls.
• Content type: application/json request and response bodies.
• Standard envelope: Every endpoint responds with { "success": bool, "messages": [], "data": <payload> }. False success values are paired with human-readable error messages (for example, missing IDs or validation failures).

Endpoint Atlas

Additional endpoints under /api/v2/lines/ cover policy type CRUD, rating table management, and copy utilities. They follow the same envelope and validation patterns described here.

Retrieving a Product Definition

1. Choose the effective date

Use the paginated list for UI experiences or find_effective_date to map a policy effective date to its governing product configuration.

curl -X POST \
  https://{tenant}.britecorepro.com/api/v2/lines/find_effective_date \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"<key>","date":"2025-01-01"}'

Successful responses include data.id, data.description, and data.effective_date. Store the id for downstream calls.

2. Understand availability by state and line

With the effective_date_id in hand:

• get_all_states returns each enabled business location (id, name, abbreviation, counties/cities, lifecycle parameters), automatically filtering out restricted locations for the requesting user.
• get_all_lines lists every line (product) available for the effective date, scoped optionally to a single location.

These lightweight endpoints are ideal for populating picklists before requesting the full product graph.

3. Retrieve the full effective date graph

retrieve_effective_date is the primary endpoint for aggregating the product definition across states, lines, policy types, and underwriting scaffolding. Provide the effective_date_id and optionally date_cursor (YYYY-MM-DD) to filter suspended lines when quoting is paused.

curl -X POST \
  https://{tenant}.britecorepro.com/api/v2/lines/retrieve_effective_date \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"<key>","effective_date_id":"<uuid>","date_cursor":"2025-01-01"}'

Key sections of the response:

• states: Enabled business locations (name, abbreviation, counties, county-level specifications).
• lines: Grouped by location_id. Each line lists policy_types with quoting flags, term availability (three_year, one_year, etc.), and system_tags that describe product taxonomy.
• underwriting_questions: Effective-date-level question catalog used before a policy type is chosen.

Each policy_types[] entry embeds:

• Underwriting options (options[] with allow/deny flags), yes/no questions, and optional validations that power pre-bind workflows.
• Flags that determine quoting behavior (e.g., open_to_quoting, multiple_property_status).
• Optional underwriting_rules summary for gating logic.

4. Drill into a specific policy type

For downstream configuration, underwriting decisions, or UI builders, call retrieve_policy_type with the policy_type_id discovered in the previous step.

curl -X POST \
  https://{tenant}.britecorepro.com/api/v2/lines/retrieve_policy_type \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"<key>","policy_type_id":"<uuid>","extend_system_tags":true}'

Highlights of the payload:

• Identity & metadata: IDs for the policy type, line, effective date, location, and template references; quoting flags per term; system_tags (optionally expanded for editor experiences).
• Coverage hierarchy:
  • items: stand-alone policy type items (coverage, adjustment, fee, etc.) with rate/limit metadata, ordering, and builder visibility.
  • sub_lines: nested groupings with their own items list.
  • line_item_groups: builder-friendly groupings of items with shared ordering.
• Deductible groups: Each group carries rounding rules and a data[] list of deductible options (amount, factor, default flag).
• Underwriting rules: Full trigger/effect definitions, module scoping (Agent/BC), exception handling, and the actions that manipulate line items.
• Underwriting options/questions: Multiselect prompts and yes/no questions with yes_no_prevent_continue semantics to guard quoting flows.
• Integrations: connected_integration_points plus a map of integration instances installed on the policy type.
• Risk support: supported_risk_types derived from quick-code values, often used to toggle vehicle/property forms.

Because the payload is large and stable, cache it per effective date/policy type combination and invalidate only when administrators publish new versions.

5. Optional helpers

• get_underwriting_question_autofill_answers: supplies recommended answers for mandatory underwriting questions, often used to seed automated test submissions or to prefill proposals.
• get_export_line_file: exports a JSON blob of the entire line (including optional custom builder sequences) for backup, migration, or import into another environment.
• list_policy_types & list_effective_dates: schema-based endpoints that support pagination and filtering when building searchable admin tools.

Error Handling and Validation Tips

• Missing IDs: Endpoints that require IDs (effective_date_id, location_id, policy_type_id) return success=false with a descriptive messages[0] element when the resource cannot be found.
• Suspensions: retrieve_effective_date automatically filters suspended lines when you pass date_cursor. Use this to present the same availability view as the agent portal.
• Access control: Agent-facing API keys may be restricted. Lines, policy types, and even states can be filtered down when the user belongs to an agency with limited authority.
• Live vs. non-live operations: Destructive endpoints (for example, deleting line items) perform a live_status check and will block changes in production tenants.

Best Practices

• Version thoughtfully: Always include both effective_date_id and location_id whenever possible. Product definitions are versioned on both axes, so caching only one dimension risks mis-applied configuration.
• Reuse metadata: system_tags and inheritance_id values allow you to correlate policy types across states or effective dates. Persist them if you need to diff versions.
• Favor validation-only runs: Copy/creation endpoints accept validate_only=true. Use that flag in automation to confirm parameters before making irreversible changes.
• Monitor payload size: retrieve_policy_type returns deeply nested arrays. When exposing the data externally, paginate or flatten sections such as items or underwriting_rules to keep responses manageable.

These APIs collectively expose the full BriteCore Lines product definition so that downstream systems—rating engines, digital quoting fronts, or migration scripts—can stay synchronized with what administrators build inside the Lines module.