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

Record a configuration package so it can be validated and applied.

Code
Takes exactly one of file_id, for a package already uploaded here through
core.uploads uploadAttachment with type 'config_package', or url, for a
presigned Amazon S3 link to one on the exporting site. A link is fetched
and stored before this returns, so what comes back always names a package
held on this site.

Nothing is executed. Hand the returned id to import_configuration
to validate it, and again to apply it.

A link import is not a cheap record: the fetch and the store run in this
request, bounded by the fetch deadline plus the upload, so one call can
hold an app worker for the better part of two minutes. A handful of
operators at a time is the expected load.

Parameters
----------
file_id : str
    A package already stored on this site, uploaded through
    core.uploads uploadAttachment with type 'config_package'.
url : str
    A presigned Amazon S3 link to a package on the exporting site. Only
    https S3 hosts are accepted and redirects are refused, because the
    fetch happens from inside the cluster.

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration import record. Its id is what to process and poll.

Raises
------
marshmallow.ValidationError
    If neither or both of file_id and url are given.

Create system tags.

delete_carbone_custom_deliverable

Export configuration settings as a package.

Code
Returns a configuration package that can be imported into another environment.
The package includes effective dates, lines, policy types, forms, items,
sublines, UW rules/questions, groups, quick quote templates, underlying
relationships, and quickcode values.

Parameters
----------
policy_type_id : str
    UUID of the policy type to export. Exports this policy type and any
    related (underlying) policy types.
skip_forms : bool, optional
    If True, skip exporting form files (PDF forms and item forms).
    Default is False.

Returns
-------
data : dict
    The configuration export record. Where the site runs Celery it comes
    back at status queued; poll get_configuration_export with its id.
    Otherwise the work runs here and the record is already complete. The
    package is never in this response either way: read it from the file
    the record names, through files/generate_download_url.

Return one configuration export by id.

Code
This is what the page polls while an export runs: status moves through
queued, processing and then complete or failed, and the record carries the
package it produced.

Parameters
----------
export_id : str

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration export record.

Return one configuration import by id.

Code
Carries the whole outcome once complete: what it touched, any warnings,
and where the package came from.

Parameters
----------
import_id : str

Returns
-------
success : bool
    True if the request was handled, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The configuration import record.

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'}

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
        }

Validate or apply a configuration package already recorded here.

Code
Takes an import_id from create_configuration_import, never the package
itself: a package reaches this site as an upload or a presigned link, and
is stored before anything runs against it. Sent twice in the ordinary
flow, once with dry_run and once without, and both runs hang off the one
record, the later replacing the earlier one's outcome.

Queues a background job where Celery is enabled and runs in this request
where it is not. Either way the answer is the record.

Validation Rules:
- Package version must be <= supported version
- Sections the declared version does not support are not imported;
  they are reported in warnings and summary.sections_not_imported
  instead of failing the request
- All location_ids in packet must exist in this environment
- Effective dates are matched by (effective_date value + location)
- Lines are unique by (line_definition_code + effective_id + location_id)
- Policy Types are unique by (policy_type_definition_code + effective_date_id + location_id)
- If entity exists with same unique key but different ID: reject
- If ID exists but unique key differs: reject
- If entity exists with same ID and unique key: update (idempotent)

Parameters
----------
import_id : str
    A package recorded by create_configuration_import.
dry_run : bool, optional
    If True, only validate the package without applying changes. Default
    is False.

Returns
-------
success : bool
    True if successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    The import record. Queued, it comes back at status queued; poll
    get_configuration_import with the same id. Run here, it is already
    complete. Either way the outcome is in ``summary``, and re-running
    replaces it:
    ::

        {
            "dry_run": bool,
            "version_compatible": bool,
            "validation_passed": bool,
            "applied": bool,  # non-dry-run transaction committed; check
                              # summary for per-section outcomes
            "warnings": [str, ...],
            "locations_affected": [str (UUID), ...],
            "summary": {
                "<section>": {...per-importer counters...},
                "sections_not_imported": [str, ...]  # populated sections
                              # dropped because the declared version does
                              # not include them, with entry counts
            }
        }

Raises
------
marshmallow.ValidationError
    If import_id is missing, unknown, or names a record with no stored
    package.
BCValidationError
    If unable to acquire lock (another import is in progress)

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

Return configuration exports, newest first.

Code
Parameters
----------
limit : int
    Page size. Defaults to 25 and is capped at 200.
offset : int
    How many to skip.
status : str
    Optional filter: queued, processing, complete or failed.

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

        {"results": [...], "total": int, "offset": int}

    With ``status``, ``total`` is advisory and a page can hold fewer
    than ``limit`` results: a lost record is settled only when read.

Return configuration imports, newest first.

Code
Parameters
----------
limit : int
    Page size. Defaults to 25 and is capped at 200.
offset : int
    How many to skip.
status : str
    Optional filter: queued, processing, complete or failed.

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

        {"results": [...], "total": int, "offset": int}

    With ``status``, ``total`` is advisory and a page can hold fewer
    than ``limit`` results: a lost record is settled only when read.

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

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"}, ...]}``.

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.

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