settings

Associate a city to a zip code. Add a city to a zip code as an override, so that the zip code will have this city as an option during the lookup of possible cities in a zip code, even if an external geolocation service disagrees.

Code
Parameters
----------
city : str
    The exact string that will be associated with the `zip_code`.
state_abbreviation : str
    The two letter abbreviation of the state (US).
    This is necessary because zip codes can cross state lines.
zip_code : str
    The five character zip code.
county : str
    An appropriate county for the specified location

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : none

Associate counties with a state. Add counties to a state, so that the state will have these counties as an option during the lookup.

Code
Parameters
----------
country: str
    The two letter abbreviation of the country (US) or (CA).
state : dict
    A dictionary containing the state or province name and
    two letter abbreviation. The name is only taking effect
    when the abbreviation is not yet registered in the system.
    If the abbreviation already exists, assigning a name will
    not alter the existing entry.
counties : list
    The list of county dictionaries that will be associated with
    the `state`. Each one contains a county name and FIPS code.
    ::

        {
            'country': str,
            'state': {
                'name': str,
                'abbreviation': str
            },
            'counties': [
                {
                    'name': str,
                    'code': str
                }
            ]
        }

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : none

Associate a county to a zip code. Add a county to a zip code as an override, so that the zip code will have this county as an option during the lookup of possible cities in a zip code, even if an external geolocation service disagrees.

Code
Parameters
----------
county : str
    The exact county string that will be associated with the `zip_code`.
state_abbreviation : str
    The two letter abbreviation of the state (US).
    This is necessary because zip codes can cross state lines.
zip_code : str
    The five character zip code.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : none

Suppress a county for a zip code. Add a county to a zip code's suppression list, so that the geocoder's report of this county for the zip code will be dropped before the county dropdown is built.

Code
Parameters
----------
county : str
    The exact county string to suppress for the `zip_code`.
state_abbreviation : str
    The two letter abbreviation of the state (US).
    This is necessary because zip codes can cross state lines.
zip_code : str
    The five character zip code.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : none

Code
Creates a new Carbone custom deliverable template and uploads the template file to the Carbone service

Parameters:
    deliverable: dict
        overwrite_stock: bool
        location_id: str
        policy_type_name: str
        custom_name: str - The deliverable name
        print_on_initial_dec: bool
        print_on_renewal_dec: bool
        print_on_non_autopay: bool
        allow_britequote_creation: bool
        module: str
        generated_per: str
        carbone_template_id: str
        source_file_name: str
        draft_carbone_template_id: str
        draft_source_file_name: str
        last_preview_entity_number: str
        dynamic_fields: list - Optional list of dynamic fields to associate with this template
Returns:
    dict: The created carbone deliverable template

Create system tags.

delete_carbone_custom_deliverable

Code
Gets the JSON context for previewing a Carbone deliverable

With no entity_id and no entity_number this returns an EXAMPLE context
instead of failing: the canonical example shipped with BriteCore, with its
static line items replaced by items generated from the selected policy
type's configuration when `policy_type_name` names one. That is what lets
Carbone Studio's data panel and preview work on a template before any
policy exists to preview against - which is most of the time a template is
being authored. In example mode `policy_type_name` / `location_id` are
SELECTORS (they resolve the policy type to generate from); with an entity
they stay validators, asserting the entity matches the dropdown.

The example context carries an `_example_meta` key describing what it is
(generated vs. the shipped fixture, which policy type resolved, how many
items per container, and the configured item names). Underscore-prefixed
so it reads as a sidecar rather than a mappable field; the caller is
expected to lift it out before handing the context to Carbone.

Parameters:
    deliverable_id - str (required if no entity_type): The ID of the deliverable to load preview data for
    entity_type - str (required if no deliverable_id): The type of entity to preview (policy, revision, claim)
    entity_id - str (optional): The ID of the entity to preview. Omit both this and
        entity_number for an example context.
    entity_number - str (optional): The number of the entity to preview. Omit both this
        and entity_id for an example context.
    location_id - str (optional): The ID of the location to restrict results for; in
        example mode, the business location narrowing policy_type_name
    policy_type_name - str (optional): The name of the policy type to restrict results
        for; in example mode, the policy type whose configured items are generated
    dynamic_field_values - dict (optional): Simulated dynamic-field values keyed by field_key,
        used to preview the `dynamic` namespace (see CarboneDeliverableTemplateService.apply_dynamic_fields)
    dynamic_fields - list of dict (optional): in-progress (not yet saved) dynamic-field
        definitions from Carbone Studio's local form state, used INSTEAD OF the
        database so an unsaved field still previews (see apply_dynamic_fields)
    calc_fields - dict (optional): {'global': [...], 'template': [...]} in-progress
        (not yet saved) calculated-field definitions, used INSTEAD OF the database
        so an unsaved field still previews (see apply_calculated_fields)

Returns:
    str: The dumped JSON context for previewing the deliverable

Gets the HTML to PDF engine used by BriteCore for custom deliverables.

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {'engine': 'weasyprint'}

Return the states and policy type definitions a setting override can target, for the overrides editor's pickers.

Code
Schemas: api_specs/request-get_setting_override_targets.json,
response-get_setting_override_targets.json.

Return a setting's per-state / per-policy-type overrides.

Code
Read on demand by the Advanced Settings editor: almost no setting has
overrides, so the settings list does not carry them.

Gets the value of a setting by section and option.

Code
Parameters
----------
section : str
    The section the setting falls under.
option : str
    The specific option we're looking for.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : str
    The value of the setting. Settings can actually be dicts, bools,
    lists, or strings but are always returned inside of a string.

Return a list of system tags.

Code
Parameters
----------

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list of dict

Return the business county names currently offered for a ZIP, pre-suppression.

Code
Parameters
----------
zip_code : str
    The five character zip code.
state_abbreviation : str
    The two letter abbreviation of the state (US).

Returns
-------
success : bool
messages : list of str
data : dict
    ::

        {
            'zip_code': str,
            'state': str,
            'candidates': list of str
        }

Return the current suppression state for a zip code.

Code
Parameters
----------
zip_code : str
    The five character zip code.
state_abbreviation : str, optional
    The two letter abbreviation of the state (US). Informational - used only
    when no row exists yet for the ZIP.

Returns
-------
success : bool
messages : list of str
data : dict
    ::

        {
            'zip_code': str,
            'state': str or None,
            'suppress_counties': list of str,
            'exists': bool  # whether a geography_overrides row exists for the ZIP
        }

List all cancellation reasons.

Code
Parameters
----------
ids : list of str, optional
    List of cancellation reason IDs to filter by, if provided.
policy_life_cycle_ids : list of str, optional
    List of policy life cycle IDs to filter by, if provided.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages.
data : object
    The data response having the form:
    ::

        {
            'cancellation_reasons': [
                {
                    'id': str,
                    'reason': str,
                    'date_added': str,
                    'policy_life_cycle_id': str
                }
            ]
        }

Code
Lists Carbone custom deliverable templates, optionally scoped to a policy type
and/or location. Global templates (no policy_type_name / no location_id set on
the row) are always included alongside an exact match on either filter.

Parameters:
    policy_type_name: str, optional
        Policy type to filter by (e.g. "DP3"). Omit for all policy types.
    location_id: str, optional
        BusinessLocation UUID to filter by. Omit for all locations.
Returns:
    list: The matching Carbone deliverable templates

Code
Lists the Carbone templates of one deliverable, live one first.

Only Carbone deliverables have retained history. History is returned for
soft-deleted deliverables.

Parameters:
    deliverable_id: str
        The x_report_locations UUID of the deliverable to read history for
Returns:
    dict: {"deliverable_id": str, "history": list} - the live template first,
        then superseded templates by version_number descending

Retrieve system tags.

Creates a new permission level rule inside Settings > Permissions.

Code
Parameters
----------
permission_level_id : str
    i.e "bd1dd7fb-5c3f-5336-94d1-7d7e0ab62808"
is_primary: boolean

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list
    List of dicts with the PermissionLevelRuleDashboard info with the form:
    ::

        {
            "dashboardId": "4495cb72-9847-4d37-8bd7-5ea91c2a143d",
            "dateAdded": "2030-01-01 00:00:00",
            "id": "2695cb72-9847-4d37-8bd7-5ea91b1a146f",
            "permissionLevelId": "7b733249-9802-4690-99ce-c911f6bd53cd"
        }

Code
Persists Carbone draft changes to the database.

Parameters:
    deliverable_id: str
    prior_draft_id: str
    new_draft_id: str
    new_draft_filename: str

Returns:
    dict: Message indicating success or failure

Remove a county from a zip code's suppression list.

Code
Parameters
----------
county : str
    The exact county string to remove from the suppression list.
zip_code : str
    The five character zip code.

Returns
-------
success : bool
messages : list of str
data : none

Deletes a permission level dashboard.

Code
Parameters
----------
permission_level_rule_dashboard_id : str
    i.e "0d1bd7eb-5c3f-4322-94d2-9d7e0aa89962"

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list
    Empty list

Preview which value a setting resolves to for a state and/or policy type definition, and which override level (if any) produced it.

Code
Reads the same resolution path the application uses, so the answer is
what a scoped read returns right now. id is the Setting UUID.

Schemas: api_specs/request-resolve_setting_override.json,
response-resolve_setting_override.json.

retrieve_admin_alert_lookups

retrieve_admin_alert_scope_overrides

retrieve_admin_alert_scopes

retrieve_admin_alerts

Retrieves the configured prompt intended prior to pulling a credit report.

Code
Parameters
----------
policy_type_id : Optional[str]
    If provided, the configured prompt on the Policy Type will be returned.
    If not, the default prompt "Have you received permission from the insured(s) to obtain their insurance score?"
    will be returned.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : object
    The data response having the form:
    ::

        {
            'prompt': 'Have you received permission from the insured(s) to obtain their insurance score?'
        }

Code
Retrieve permissions for this user with given prefixes.
Returns all permissions from registry if no prefixes provided.

Parameters
----------
prefixes : list of str
    List of filtering prefixes for permissions list.

Returns
-------
success : bool
    Whether or not the request was successful.
messages : list of str
    List of human-readable error messages.
data : dict
    An object of the following format.

    ::

        {
            'permissions': [
                {
                    'read': '',
                    'write': '',
                    'section': ''
                }
            ]
        }

Check whether the current user can perform a property replacement cost valuation on the policy.

Code
Parameters
----------
is_app : bool
    True is the policy is an application and False if it is a quote.
revision_id : str
    ID of the revision whose property valuation availability is being questioned.
chosen_role : str

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The data response having the form:
    ::

        {
            'allow_property_valuation': bool  # True if property valuation is allowed.
        }

Retrieves list of quick code value tags

Lists Advanced Settings grouped by section.

Code
Exposes over REST the section/settings structure the Advanced Settings admin
screen consumes, so API callers (e.g. the settings MCP tool) can enumerate
sections, options, current values, and value types without the internal
gateway. Read-only; requires the same ``britecore/settings/advancedSettings``
'r' permission that gates the Advanced Settings UI page, since bulk
enumeration of every setting's value is a materially larger blast radius
than the single-key ``get_setting_value`` lookup.

The request/response formats are documented by the JSON schemas at
``lib/api/api_specs/request-retrieve_settings.json`` and
``lib/api/api_specs/response-retrieve_settings.json``.

Parameters
----------
section : str, optional
    When provided, only that section is returned; otherwise every section.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list of dict
    Sections, each ``{"name": <section>, "settings": [{"id", "section",
    "option", "value", "value_type", "description", "options",
    "accepts_overrides"}, ...]}``.

Retrieves information about system tags

Code
Parameters
----------
level : str (optional, default 'all')
    The level at which the resulting tags are allowed to tag.
    ('line', 'policy_type', 'sub_line',
     'policy_type_item', 'category', 'question',
     'claim', 'contact', 'policy')
include_select : boolean (optional, default False)
    Include tags with 'select' as style

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list
    The data response having the form:
    ::

        [
            {
                'id': 'UUID',
                'name': 'Tag Name',
                'required': boolean,
                'type': ('internal', 'report', 'vendor', 'custom'),
                'style': ('text', 'checkbox', 'select'),
                'line': boolean,
                'policy_type': boolean,
                'sub_lines': boolean,
                'policy_type_item': boolean,
                'category': boolean,
                'question': boolean,
                'claim': boolean,
                'contact': boolean,
                'policy': boolean,
                'quick_code': 'Quick Code',
            }
        ]

Code
Retrieves the template setup for a Carbone deliverable

Returns
-------
dict:
    systemDocuments: A list of report type names used for Carbone reports
    policyTypesLocations: a list of policy types and their associated business locations
    existingDeliverables: a list of all Carbone deliverables with their details, including their associated policy
     type and location

Sets the HTML to PDF engine used by BriteCore for custom deliverables.

Code
Parameters
----------
engine : str, required
    The name of the PDF engine to use for processing custom deliverables in BriteCore. (weasyprint, wkhtmltopdf)

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : none

Sets the value of a setting by section and option.

Code
Parameters
----------
section : str
    The section the setting falls under.
option : str
    The specific option we're looking for.
value : str
    The value to se the setting|option to.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : str
    The value of the setting. Settings can actually be dicts, bools,
    lists, or strings but are always returned inside of a string.

update_admin_alert_scope_overrides

update_admin_alerts

Code
Updates an existing Carbone custom deliverable template

Parameters:
    deliverable: dict
        id: str - The ID of the deliverable to update
        location_id: str
        policy_type_name: str
        custom_name: str - The deliverable name
        overwrite_stock: bool
        carbone_template_id: str
        source_file_name: str
        draft_carbone_template_id: str
        draft_source_file_name: str
        last_preview_entity_number: str
        print_on_initial_dec: bool
        print_on_renewal_dec: bool
        print_on_non_autopay: bool
        allow_britequote_creation: bool
        module: str
        generated_per: str
        dynamic_fields: list - (Optional) list of dynamic fields to associate with this template
        deleted_dynamic_field_ids: list - (Optional) list of dynamic field IDs to delete
Returns:
    dict: The updated carbone deliverable template

Updates the given permission level dashboard.

Code
Parameters
----------
permission_level_rule_dashboard_id : str
    i.e "0d1bd7eb-5c3f-4322-94d2-9d7e0aa89962"
dashboard_id : str
    i.e "bd1bd7eb-5c3f-4366-94d1-9d7e0aa62899"
is_primary: boolean

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : list
    Empty list

Replace a setting's per-state / per-policy-type overrides.

Code
The structured editor POSTs the full list of override entries, each a
{location_id, policy_type_definition_code, value} with one or both
targets set; all validation, coercion, the write (via SettingsService, to
keep the override cache consistent) and the audit note happen in
SettingController.update_setting_overrides.

This endpoint cannot change a setting's global value -- globals live in
settings.value and keep their existing save path and authorization.

id is the Setting UUID; value is the override list (list/dict, or a
pre-serialized JSON string of it). Either form is validated and
normalized by the controller before persistence -- it is not stored
byte-for-byte.

Create or update system tags by id.