API Reference

Last updated: July 20, 2026

This section provides symbol-level API documentation grouped by business domain. For narrative usage guidance and broader endpoint notes, see API.md.

Notable SDK additions

  • BritecoreAPIClient - context manager (__enter__/__exit__), __repr__, init_client() returns Self

  • do_request(..., dry_run=True) - synthetic dry-run response with redacted headers by default

  • init_api_client(client_dry_run=True) / init_client(client_dry_run=True) - client-level dry-run defaults

  • init_async_api_client(client_dry_run=True) / AsyncBritecoreAPIClient.ado_request(..., dry_run=True) - async dry-run parity with cache bypass

  • reset_api_client() - clears module-level client (test isolation)

  • HealthcheckResult.__bool__ - truthiness from .ok

  • Flat exception aliases in britecore_sdk.exceptions and top-level package

Package exports

BriteCore Libraries - Core utilities for BriteCore API integration.

This package provides: - Domain models for contacts and policies - Validators for data normalization - API clients and authentication - Custom exceptions

Top-level convenience exports (for example BritecoreError, NotFoundError, get_api_client) are documented in their source modules below to avoid duplicate symbol definitions.

API clients

Wrapper for BriteCore API calls

class britecore_sdk.api.britecore_api_client.LoadClientSettings(target_site)[source]

Bases: object

Loads and manages client configuration settings for a specified target site.

This class is responsible for initializing with a target site and loading configuration settings that combine default settings with site-specific overrides. It retrieves the target site from either constructor argument or environment variable and uses it to fetch appropriate settings.

Parameters:

target_site (str)

load_config()[source]

Load and return configuration settings for the target site.

Switches Dynaconf into the target-site environment (which automatically inherits [default] values) and snapshots all needed keys into a plain SimpleNamespace so the result remains valid after the context exits.

Returns:

Combined configuration settings for the target site.

Return type:

SimpleNamespace

class britecore_sdk.api.britecore_api_client.BritecoreAPIClient(target_site)[source]

Bases: object

Client for interacting with the Britecore API.

This class provides functionality to initialize an API client with configuration settings, handle authentication using either API keys or OAuth tokens, and execute HTTP requests to Britecore API endpoints.

All state is instance-level; multiple clients can coexist in the same process without interfering with each other.

Parameters:

target_site (str)

init_client(*, client_dry_run=False, debug_include_request_body=False, base_url=None, api_key=None, client_id=None, client_secret=None, enable_rate_limiter=None, rate_limiter_requests_per_second=None, rate_limiter_burst_size=None, rate_limiter_adaptive_backoff=None, rate_limiter_backoff_timeout_seconds=None)[source]

Initializes the Britecore API client with configuration settings and HTTP components.

This method sets up the client by loading site-specific settings, configuring HTTP timeouts and retries, and initializing authentication components. It ensures that all necessary configuration parameters are present and valid before proceeding with client initialization.

Logging behavior:

  • DEBUG logs are emitted throughout for configuration discovery and auth mode selection

  • ERROR logs are emitted for any configuration validation failures (missing base_url, missing api_key, OAuth initialization errors, rate limiter configuration errors, etc.) before raising exceptions. This ensures failures are captured in application logs even if exceptions are caught by caller code.

  • INFO log is emitted on successful initialization, including auth mode and rate limiting status.

Credentials can be supplied in two mutually exclusive ways:

File-based (default): omit all credential kwargs — LoadClientSettings reads values from the layered config file search hierarchy (see _discover_settings_files()).

Explicit (inline): pass base_url (required) plus any combination of api_key, client_id, and client_secret. When base_url is given, the file-based lookup is skipped entirely and only the supplied values are used.

Rate Limiting (optional): pass enable_rate_limiter=True to enable client-side rate limiting. Configuration can be provided explicitly via rate_limiter_* parameters, or read from settings.toml if omitted.

Returns:

The initialized client instance, allowing fluent one-liner construction:

client = BritecoreAPIClient("my_site").init_client()

# With rate limiting enabled:
client = BritecoreAPIClient("my_site").init_client(
    enable_rate_limiter=True,
    rate_limiter_requests_per_second=5,
)

# Explicit-credential variant (no config file required):
client = BritecoreAPIClient("my_site").init_client(
    base_url="https://api.example.com",
    api_key="my-key",
    enable_rate_limiter=True,
)

Return type:

Self

Parameters:

  • client_dry_run (bool) – When True, requests inherit dry-run behavior unless a specific call passes dry_run=False. This is useful for testing SDK wrapper flow and payload shaping without sending requests.

  • debug_include_request_body (bool) – When True, the unredacted request body is attached to raised exceptions for interactive debugging. Defaults to False; the sanitized (PII-redacted) body is used instead. Do not enable in production environments.

  • base_url (str | None) – Override (or supply) the site base URL directly. When provided, the file-based LoadClientSettings lookup is bypassed.

  • api_key (str | None) – Explicit API key. Used only when base_url is also given.

  • client_id (str | None) – Explicit OAuth client ID. Used only when base_url is given.

  • client_secret (str | None) – Explicit OAuth client secret. Used only when base_url is given.

  • enable_rate_limiter (bool | None) – Enable client-side rate limiting. When None (default), reads from settings rate_limiter_enabled. When True or False, overrides the setting.

  • rate_limiter_requests_per_second (float | None) – Target request rate for rate limiter (default: 10.0 req/s from settings). Only used if rate limiter is enabled.

  • rate_limiter_burst_size (int | None) – Maximum burst capacity for rate limiter (default: 20 requests from settings). Only used if rate limiter is enabled.

  • rate_limiter_adaptive_backoff (bool | None) – Enable automatic backoff on 429 responses (default: True from settings). Only used if rate limiter is enabled.

  • rate_limiter_backoff_timeout_seconds (float | None) – Duration to back off after 429 (default: 60.0 seconds from settings). Only used if rate limiter is enabled.

Raises:
process_result(response, logs=False, endpoint=None, request_id=None, sanitized_body=None)[source]

Process HTTP response and extract data from successful API calls.

This instance method handles the processing of HTTP responses from API calls, validating the response status, parsing JSON data, and raising appropriate exceptions for errors or missing data. The method has access to the client instance, allowing it to update the rate limiter when needed.

Parameters:

  • response (HTTPResponse | BaseHTTPResponse | None) – HTTPResponse object containing the API response

  • logs (bool) – Boolean flag to enable debug logging of the response data

  • endpoint (str | None) – Optional endpoint path for error context and diagnostics

  • request_id (str | None) – Optional correlation ID from the originating do_request call. When provided (or discoverable from the response headers), it is attached to every exception raised here so callers can cross-reference the request in server-side logs.

  • sanitized_body (Any | None) – Optional sanitized request body to attach to raised exceptions for offline inspection without logging PII.

Returns:

Parsed data from the API response if successful

Raises:

BritecoreError.NoDataReturned – When response is None, status code is not 200, or the API returns a failure status

Return type:

Any

do_request(path, json=None, request_timeout=None, request_retries=None, request_headers=None, method='POST', cache_enabled=False, cache_ttl_seconds=None, cache_namespace=None, cache_key_parts=None, cache_bypass=False, cache_invalidate_on_success=None, dedupe_in_flight=True, dry_run=None, dry_run_include_sensitive_headers=False, rate_limiter_bypass=False)[source]

Execute an HTTP request to the specified path with optional JSON payload and headers.

Parameters:

  • path (str) – The endpoint path to which the request is sent.

  • json (Optional[dict[str, Any]]) – The JSON payload to send with the request.

  • request_timeout (Optional[Timeout]) – The timeout configuration for the request.

  • request_retries (Optional[Retry]) – The retry configuration for the request.

  • request_headers (Optional[dict[str, Any]]) – Custom headers to include in the request.

  • method (Optional[str]) – The HTTP method to use for the request, defaults to “POST”.

  • dry_run (bool | None) – If True, log the full request details and return a synthetic successful response without sending the request. If None, inherit the client’s client_dry_run setting.

  • dry_run_include_sensitive_headers (bool) – If True, include unredacted headers in dry-run logs/response. Defaults to False for safety.

  • rate_limiter_bypass (bool) – If True, bypass the client-side rate limiter for this request. Defaults to False. Only applicable when rate limiter is enabled on the client.

  • cache_enabled (bool)

  • cache_ttl_seconds (int | None)

  • cache_namespace (str | None)

  • cache_key_parts (list[str] | tuple[str, ...] | None)

  • cache_bypass (bool)

  • cache_invalidate_on_success (list[str] | tuple[str, ...] | None)

  • dedupe_in_flight (bool)

Returns:

The response from the HTTP request.

Return type:

Optional[urllib3.HTTPResponse | urllib3.BaseHTTPResponse]

Raises:
classmethod multiple_parameter_verification(parameter_list, parameter_priority)[source]

Verify multiple parameters and return the correct one based on priority.

This method takes a list of parameter dictionaries and a priority list to determine which parameter should be used when multiple parameters are present. If multiple parameters are found, the method selects the one with the highest priority. If no parameters are found, it returns the first parameter from the priority list.

Parameters:

  • parameter_list (list[dict[str, str | None]]) – List of dictionaries containing parameters

  • parameter_priority (list[str]) – List of parameter names in order of priority

Returns:

Dictionary containing the selected parameter

Return type:

dict[str, str | None]

classmethod json_dict_builder(request_arguments)[source]

Takes all passed parameters and combines all non-empty values into one dictionary :param request_arguments: All arguments passed from a function :type request_arguments: dict[str,Any]

Parameters:

request_arguments (dict[str, Any])

Return type:

dict[str, Any]

static create_full_quotes_batch(quotes_json, max_workers=5, fail_fast=False, **kwargs)[source]

Create many quotes concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.batch_quotes.create_full_quotes_batch(). See that function for full documentation.

Parameters:

  • quotes_json (list[Any]) – List of quote payload dictionaries.

  • max_workers (int) – Maximum concurrent workers. Defaults to 5.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Unpack[RequestParameters]) – RequestParameters passed through to each quote create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

static create_contacts_batch(contacts_json, max_workers=5, fail_fast=False, **kwargs)[source]

Create many contacts concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.batch_contacts.create_contacts_batch(). See that function for full documentation.

Parameters:

  • contacts_json (list[Any]) – List of contact payload dicts (each must contain name and address).

  • max_workers (int) – Maximum concurrent workers. Defaults to 5.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Unpack[RequestParameters]) – RequestParameters passed through to each contact create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

static create_policies_batch(policies_json, max_workers=3, fail_fast=False, **kwargs)[source]

Create many policies concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.batch_policies.create_policies_batch(). See that function for full documentation.

Parameters:

  • policies_json (list[Any]) – List of policy payload dicts forwarded as kwargs to create_policy.

  • max_workers (int) – Maximum concurrent workers. Defaults to 3.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Unpack[RequestParameters]) – RequestParameters passed through to each policy create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

static create_risks_batch(risks_json, max_workers=3, fail_fast=False, **kwargs)[source]

Create many risks concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.batch_policies.create_risks_batch(). See that function for full documentation.

Parameters:

  • risks_json (list[Any]) – List of risk payload dicts (each must contain revision_id).

  • max_workers (int) – Maximum concurrent workers. Defaults to 3.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Unpack[RequestParameters]) – RequestParameters passed through to each risk create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

class britecore_sdk.api.britecore_api_client.RequestParameters[source]

Bases: TypedDict

Optional keyword parameters accepted by API request wrapper functions.

request_timeout: NotRequired[Timeout]
request_retries: NotRequired[Retry]
request_headers: NotRequired[dict[str, Any]]
cache_enabled: NotRequired[bool]
cache_ttl_seconds: NotRequired[int]
cache_namespace: NotRequired[str]
cache_key_parts: NotRequired[list[str] | tuple[str, ...]]
cache_bypass: NotRequired[bool]
cache_invalidate_on_success: NotRequired[list[str] | tuple[str, ...]]
dedupe_in_flight: NotRequired[bool]
dry_run: NotRequired[bool]
dry_run_include_sensitive_headers: NotRequired[bool]
rate_limiter_bypass: NotRequired[bool]

Async facade for the synchronous BriteCore API client.

class britecore_sdk.api.britecore_async_api_client.AsyncBritecoreAPIClient(target_site=None, client=None, cache=None, default_cache_ttl_seconds=60, async_transport='threaded', httpx_client=None, client_dry_run=None, base_url=None, api_key=None, client_id=None, client_secret=None)[source]

Bases: object

Async wrapper around BritecoreAPIClient with in-memory response caching.

Parameters:

  • target_site (str | None)

  • client (BritecoreAPIClient | None)

  • cache (RequestCache | None)

  • default_cache_ttl_seconds (int)

  • async_transport (_AsyncTransport)

  • httpx_client (Any | None)

  • client_dry_run (bool | None)

  • base_url (str | None)

  • api_key (str | None)

  • client_id (str | None)

  • client_secret (str | None)

async aget_client()[source]

Return the configured sync client, initializing it lazily if necessary.

Return type:

BritecoreAPIClient

clear_cache()[source]

Clear all cached responses.

Return type:

None

invalidate_cache_namespaces(namespaces)[source]

Invalidate cached responses for the given namespaces.

Parameters:

namespaces (list[str] | tuple[str, ...])

Return type:

int

async aprocess_result(response, logs=False)[source]

Process a sync HTTP response in the same way as BritecoreAPIClient.

Parameters:

  • response (BaseHTTPResponse)

  • logs (bool)

Return type:

Any

async ado_request(path, json=None, request_timeout=None, request_retries=None, request_headers=None, method='POST', cache_enabled=False, cache_ttl_seconds=None, cache_namespace=None, cache_key_parts=None, cache_bypass=False, cache_invalidate_on_success=None, dedupe_in_flight=True, rate_limiter_bypass=False, dry_run=None, dry_run_include_sensitive_headers=False)[source]

Execute a request asynchronously with optional response caching.

Parameters:

  • path (str)

  • json (dict[str, Any] | None)

  • request_timeout (Timeout | None)

  • request_retries (Retry | None)

  • request_headers (dict[str, Any] | None)

  • method (str | None)

  • cache_enabled (bool)

  • cache_ttl_seconds (int | None)

  • cache_namespace (str | None)

  • cache_key_parts (list[str] | tuple[str, ...] | None)

  • cache_bypass (bool)

  • cache_invalidate_on_success (list[str] | tuple[str, ...] | None)

  • dedupe_in_flight (bool)

  • rate_limiter_bypass (bool)

  • dry_run (bool | None)

  • dry_run_include_sensitive_headers (bool)

Return type:

BaseHTTPResponse | None

async static acreate_full_quotes_batch(quotes_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Create many quotes concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.async_batch_quotes.acreate_full_quotes_batch(). See that function for full documentation.

Parameters:

  • quotes_json (list[Any]) – List of quote payload dictionaries.

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 5.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each quote create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

async static acreate_contacts_batch(contacts_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Create many contacts concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.async_batch_contacts.acreate_contacts_batch(). See that function for full documentation.

Parameters:

  • contacts_json (list[Any]) – List of contact payload dicts (each must contain name and address).

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 5.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each contact create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

async static acreate_policies_batch(policies_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Create many policies concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.async_batch_policies.acreate_policies_batch(). See that function for full documentation.

Parameters:

  • policies_json (list[Any]) – List of policy payload dicts forwarded as kwargs to acreate_policy.

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 3.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each policy create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

async static acreate_risks_batch(risks_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Create many risks concurrently and return per-item outcomes.

Delegates to britecore_sdk.api.workflows.async_batch_policies.acreate_risks_batch(). See that function for full documentation.

Parameters:

  • risks_json (list[Any]) – List of risk payload dicts (each must contain revision_id).

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 3.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each risk create call.

Returns:

dict with total, succeeded, failed, and results keys.

Return type:

dict[str, Any]

Shared request-cache primitives for API clients.

britecore_sdk.api.request_cache.build_cache_key(*, target_site, method, path, json_payload=None, request_headers=None, cache_namespace=None, cache_key_parts=None)[source]

Build a stable cache key for a request.

Parameters:

  • target_site (str | None)

  • method (str)

  • path (str)

  • json_payload (Mapping[str, Any] | None)

  • request_headers (Mapping[str, Any] | None)

  • cache_namespace (str | None)

  • cache_key_parts (Iterable[str] | None)

Return type:

str

class britecore_sdk.api.request_cache.CacheEntry(value, expires_at, namespace='', created_at=<factory>)[source]

Bases: object

Single cached response value with expiration metadata.

Parameters:

  • value (Any)

  • expires_at (datetime)

  • namespace (str)

  • created_at (datetime)

value: Any
expires_at: datetime
namespace: str
created_at: datetime
is_expired(now=None)[source]

Return True when the cache entry is expired.

Parameters:

now (datetime | None)

Return type:

bool

class britecore_sdk.api.request_cache.RequestCache[source]

Bases: object

Thread-safe in-memory TTL cache for API responses.

get(key)[source]

Return a cached value when present and unexpired.

Parameters:

key (str)

Return type:

Any | None

set(key, value, ttl_seconds, namespace='')[source]

Store a value in the cache when the TTL is positive.

Parameters:

  • key (str)

  • value (Any)

  • ttl_seconds (int)

  • namespace (str)

Return type:

None

invalidate_namespace(namespace)[source]

Remove all entries belonging to the given namespace.

Parameters:

namespace (str)

Return type:

int

invalidate_namespaces(namespaces)[source]

Remove all entries for the provided namespaces.

Parameters:

namespaces (Iterable[str])

Return type:

int

clear()[source]

Remove all cache entries.

Return type:

None

prune_expired()[source]

Remove expired entries and return the number removed.

Return type:

int

Exceptions

BriteCore custom exceptions.

v2.0.0 Enhanced Error Model

All exceptions now include structured metadata for better error handling:

  • status_code: HTTP status code (e.g., 400, 404, 500)

  • error_code: BriteCore error code (e.g., “quote_not_found”, “invalid_field”)

  • request_id: Request correlation ID for debugging (e.g., “abc123def456”)

  • detail: Human-readable error message

  • raw_payload: Full server response dict for debugging

  • sanitized_body: Redacted request body for safe debugging

Example

try:

retrieve_quote(quote_number=”INVALID”, client=client)

except NotFoundError as e:

print(f”Status: {e.status_code}”) # 404 print(f”Code: {e.error_code}”) # “quote_not_found” print(f”Request ID: {e.request_id}”) # “abc123def456” print(f”Detail: {e.detail}”) # “Quote INVALID does not exist” print(f”Raw: {e.raw_payload}”) # {“success”: false, …}

class britecore_sdk.exceptions.BritecoreError[source]

Bases: object

Namespace for custom exceptions related to BriteCore operations.

exception Base(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Exception

Base class for all SDK-originated exceptions.

v2.0.0 Enhanced with structured metadata: - status_code: HTTP status code - error_code: BriteCore error code - request_id: Request correlation ID - detail: Human-readable error message - raw_payload: Full server response - hint: Optional troubleshooting suggestion

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception NoDataReturned(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: Base

Raised when BriteCore API returns no usable data.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception NoTokenReturned(message, request=None, http_error=None, http_status=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: Base

Raised when OAuth token request fails.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • http_status (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception InvalidPhoneNumber(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when phone number validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception InvalidEmailAddress(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when email address validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception InvalidAddress(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when address validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception BritecoreKeyError(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when a required key is missing.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception NoSiteError(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when no target site is assigned.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception MissingParameter(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when a required parameter is missing.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception ConflictingParameters(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when multiple conflicting parameters are specified.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception AuthenticationError(message, http_status=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when API authentication fails (invalid key, expired token, 401/403).

Parameters:

  • message (str)

  • http_status (int | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception RateLimitError(message, retry_after=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: Base

Raised when the API rate limit is exceeded (HTTP 429).

Parameters:

  • message (str)

  • retry_after (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception ServerError(message, http_status=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: Base

Raised when the API returns a 5xx server error.

Parameters:

  • message (str)

  • http_status (int | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception ValidationError(message, request=None, http_error=None, endpoint=None, http_status=None, *, validation_errors=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: NoDataReturned

Raised when API validation fails (for example HTTP 400/422).

v2.0.0 Enhancement: includes validation_errors dict with field-level details.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • validation_errors (dict[str, Any] | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception NotFoundError(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: NoDataReturned

Raised when an API resource is not found (HTTP 404).

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception ConflictError(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: NoDataReturned

Raised when API returns a conflict (HTTP 409).

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception ConfigurationError(message, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)[source]

Bases: Base

Raised when the client is misconfigured (missing base_url, api_key, etc.).

Parameters:

  • message (str)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception RequestTimeoutError(message, timeout_seconds=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)[source]

Bases: Base

Raised when an API request exceeds its configured timeout.

Parameters:

  • message (str)

  • timeout_seconds (int | float | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

britecore_sdk.exceptions.BritecoreBaseError

alias of Base

exception britecore_sdk.exceptions.NoDataReturned(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: Base

Raised when BriteCore API returns no usable data.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.NoTokenReturned(message, request=None, http_error=None, http_status=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: Base

Raised when OAuth token request fails.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • http_status (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.AuthenticationError(message, http_status=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when API authentication fails (invalid key, expired token, 401/403).

Parameters:

  • message (str)

  • http_status (int | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.RateLimitError(message, retry_after=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: Base

Raised when the API rate limit is exceeded (HTTP 429).

Parameters:

  • message (str)

  • retry_after (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.ServerError(message, http_status=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: Base

Raised when the API returns a 5xx server error.

Parameters:

  • message (str)

  • http_status (int | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.ValidationError(message, request=None, http_error=None, endpoint=None, http_status=None, *, validation_errors=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: NoDataReturned

Raised when API validation fails (for example HTTP 400/422).

v2.0.0 Enhancement: includes validation_errors dict with field-level details.

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • validation_errors (dict[str, Any] | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.NotFoundError(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: NoDataReturned

Raised when an API resource is not found (HTTP 404).

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.ConflictError(message, request=None, http_error=None, endpoint=None, http_status=None, *, status_code=None, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: NoDataReturned

Raised when API returns a conflict (HTTP 409).

Parameters:

  • message (str)

  • request (str | None)

  • http_error (str | None)

  • endpoint (str | None)

  • http_status (int | None)

  • status_code (int | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.ConfigurationError(message, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when the client is misconfigured (missing base_url, api_key, etc.).

Parameters:

  • message (str)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.RequestTimeoutError(message, timeout_seconds=None, endpoint=None, *, error_code=None, request_id=None, raw_payload=None, sanitized_body=None)

Bases: Base

Raised when an API request exceeds its configured timeout.

Parameters:

  • message (str)

  • timeout_seconds (int | float | None)

  • endpoint (str | None)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

Return type:

None

exception britecore_sdk.exceptions.BritecoreKeyError(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when a required key is missing.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.NoSiteError(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when no target site is assigned.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.MissingParameter(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when a required parameter is missing.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.ConflictingParameters(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when multiple conflicting parameters are specified.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.InvalidPhoneNumber(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when phone number validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.InvalidEmailAddress(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when email address validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

exception britecore_sdk.exceptions.InvalidAddress(message, *, status_code=500, error_code=None, request_id=None, raw_payload=None, sanitized_body=None, hint=None)

Bases: Base

Raised when address validation fails.

Parameters:

  • message (str)

  • status_code (int)

  • error_code (str | None)

  • request_id (str | None)

  • raw_payload (dict[str, Any] | None)

  • sanitized_body (Any | None)

  • hint (str | None)

Return type:

None

Utilities

SDK healthcheck utility for configuration/auth/readiness validation.

class britecore_sdk.utils.healthcheck.HealthcheckResult(ok, site, auth_mode, config_ok, api_ok, message)[source]

Bases: object

Structured healthcheck result for CLI and programmatic use.

Parameters:

  • ok (bool)

  • site (str)

  • auth_mode (str)

  • config_ok (bool)

  • api_ok (bool)

  • message (str)

ok: bool
site: str
auth_mode: str
config_ok: bool
api_ok: bool
message: str
britecore_sdk.utils.healthcheck.run_healthcheck(target_site=None, ping=True)[source]

Run configuration/auth checks and optional safe API ping.

Parameters:

  • target_site (str | None) – Configured site section to validate. If omitted, resolves from settings/env using get_target_site().

  • ping (bool) – Whether to call a safe read-only endpoint.

Returns:

Structured validation status.

Return type:

HealthcheckResult

britecore_sdk.utils.healthcheck.main(argv=None)[source]

CLI entrypoint for python -m britecore_sdk.utils.healthcheck.

Parameters:

argv (list[str] | None)

Return type:

int

V2 package exports

Version 2 API wrappers, including async variants and batch aliases.

Sync domain modules

Import a domain module to access its endpoint wrappers:

from britecore_sdk.api.api_calls.v2 import policies
result = policies.retrieve_policy(policy_number="POL-001")

All sync domain modules are listed in __all__ and are importable directly from this package.

Async helpers and batch aliases

This package re-exports async v2 wrapper functions and exposes lazy, backwards-compatible aliases for workflow batch helpers.

britecore_sdk.api.api_calls.v2.create_contacts_batch(contacts_json, max_workers=5, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows create_contacts_batch(…).

Parameters:

  • contacts_json (list[dict[str, Any]])

  • max_workers (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

britecore_sdk.api.api_calls.v2.create_full_quotes_batch(quotes_json, max_workers=5, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows create_full_quotes_batch(…).

Parameters:

  • quotes_json (list[dict[str, Any]])

  • max_workers (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

britecore_sdk.api.api_calls.v2.create_policies_batch(policies_json, max_workers=3, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows create_policies_batch(…).

Parameters:

  • policies_json (list[dict[str, Any]])

  • max_workers (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

britecore_sdk.api.api_calls.v2.create_risks_batch(risks_json, max_workers=3, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows create_risks_batch(…).

Parameters:

  • risks_json (list[dict[str, Any]])

  • max_workers (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

async britecore_sdk.api.api_calls.v2.aadd_contact_to_role(contact_id, role='Named Insured', **kwargs)[source]

Add a contact to a named role asynchronously.

POST /api/v2/contacts/add_contact_to_role

Parameters:

  • contact_id (str)

  • role (Literal['Additional Insured', 'Additional Interest', 'Administrator', 'Agent', 'Attorney', 'Board Member', 'Claim Administrator', 'Claimant', 'Claims Adjuster', 'Claims Supervisor', 'Contractor', 'Driver', 'Employee', 'External Claims Adjuster', 'In Care Of', 'Inspector', 'Loss Payee', 'Medical Provider', 'Named Insured', 'Public Claims Adjuster', 'Surplus Lines Producer', 'Underwriter', 'Unlisted Payor', 'Vendor'] | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aadd_line_item(revision_id, item_id, property_id='', sub_line_id='', link_id='', check_for_subline=False, **kwargs)[source]

Add a line item to a revision or property asynchronously.

POST /api/v2/policies/add_line_item

Parameters:

  • revision_id (str)

  • item_id (str)

  • property_id (str | None)

  • sub_line_id (str | None)

  • link_id (str | None)

  • check_for_subline (bool | None)

  • kwargs (Unpack[RequestParameters])

Return type:

bool

async britecore_sdk.api.api_calls.v2.acreate_contacts_batch(contacts_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows acreate_contacts_batch(…).

Parameters:

  • contacts_json (list[dict[str, Any]])

  • max_concurrent (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

async britecore_sdk.api.api_calls.v2.acreate_full_quote(quote_json, **kwargs)[source]

Create a full quote asynchronously.

Use quote_json for the complete quote payload expected by the quote-create workflow exposed by this SDK. Returns the async aprocess_result(...) payload together with the extracted quote ID, invalidates cached quote reads on success, and accepts RequestParameters overrides via **kwargs.

Parameters:
Return type:

tuple[dict[str, Any] | None, str | None]

async britecore_sdk.api.api_calls.v2.acreate_full_quotes_batch(quotes_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows acreate_full_quotes_batch(…).

Parameters:

  • quotes_json (list[dict[str, Any]])

  • max_concurrent (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

async britecore_sdk.api.api_calls.v2.acreate_policies_batch(policies_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows acreate_policies_batch(…).

Parameters:

  • policies_json (list[dict[str, Any]])

  • max_concurrent (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

async britecore_sdk.api.api_calls.v2.acreate_policy(policy_number='', policy_type_id='', inception_date='', term_type='1 Year', expiration_date='', renewal_term_type='1 Year', is_renewal=False, as_agent=False, manual_policy_number=True, effective_date='', property_zip='', underwriting_questions=None, underwriting_options=None, external_system_reference='', **kwargs)[source]

Create a new policy asynchronously.

The payload mirrors /api/v2/policies/create_policy and accepts policy, term, underwriting, and external reference fields, including the documented custom-term expiration requirement. Returns the async aprocess_result(...) payload together with the new revision_id, invalidates cached policy reads on success, and accepts RequestParameters overrides.

Parameters:

  • policy_number (str | None) – The policy number (default empty string).

  • policy_type_id (str | None) – The policy type identifier.

  • inception_date (str | None) – Policy inception date.

  • term_type (Literal['Custom', '3 Years', '18 Months', '1 Year', '9 Months', '6 Months', '3 Months'] | None) – The term type (default ‘1 Year’). When ‘Custom’, expiration_date is required.

  • expiration_date (str | None) – Policy expiration date (required when term_type is ‘Custom’).

  • renewal_term_type (Literal['3 Years', '18 Months', '1 Year', '9 Months', '6 Months', '3 Months'] | None) – The renewal term type (default ‘1 Year’).

  • is_renewal (bool | None) – Whether this is a renewal policy (default False).

  • as_agent (bool | None) – Whether creating as an agent (default False).

  • manual_policy_number (bool | None) – Whether the policy number is manually entered (default True).

  • effective_date (str | None) – Policy effective date.

  • property_zip (str | None) – Primary property ZIP code.

  • underwriting_questions (list[Any] | None) – List of underwriting question responses.

  • underwriting_options (list[Any] | None) – List of underwriting option selections.

  • external_system_reference (str | None) – External system reference identifier.

  • **kwargs (Unpack[RequestParameters]) – Additional request parameters and cache invalidation settings.

Returns:

A tuple of (processed_policy_data, revision_id).

Return type:

tuple[Any, str]

Raises:
async britecore_sdk.api.api_calls.v2.acreate_risk(revision_id, property_group_number=None, building_number=None, force_categories=None, **kwargs)[source]

Create a risk for a revision asynchronously.

POST /api/v2/policies/create_risk

Parameters:

  • revision_id (str)

  • property_group_number (int | None)

  • building_number (int | None)

  • force_categories (bool | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.acreate_risks_batch(risks_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Backward-compatible alias to workflows acreate_risks_batch(…).

Parameters:

  • risks_json (list[dict[str, Any]])

  • max_concurrent (int)

  • fail_fast (bool)

  • kwargs (Unpack[RequestParameters])

Return type:

dict[str, Any]

async britecore_sdk.api.api_calls.v2.afind_contact_by_params(name, role_name=None, dob=None, **kwargs)[source]

Find contacts by the supported search parameters with async caching.

POST /api/v2/contacts/find_contact_by_params

Parameters:

  • name (str)

  • role_name (Literal['Additional Insured', 'Additional Interest', 'Administrator', 'Agent', 'Attorney', 'Board Member', 'Claim Administrator', 'Claimant', 'Claims Adjuster', 'Claims Supervisor', 'Contractor', 'Driver', 'Employee', 'External Claims Adjuster', 'In Care Of', 'Inspector', 'Loss Payee', 'Medical Provider', 'Named Insured', 'Public Claims Adjuster', 'Surplus Lines Producer', 'Underwriter', 'Unlisted Payor', 'Vendor'] | None)

  • dob (str | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aget_contact(contact_id, **kwargs)[source]

Retrieve a contact by identifier with short-lived async caching.

POST /api/v2/contacts/get_contact

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.aget_quote(quote_id, **kwargs)[source]

Retrieve a quote by ID with short-lived async caching enabled by default.

The request uses quote_id to fetch the quote through the async quote client and enables the default quote read cache unless the caller overrides it. Returns the async aprocess_result(...) payload, and **kwargs accepts RequestParameters plus cache override settings.

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.anew_contact(name, address, phone=None, email=None, contact_type='individual', **kwargs)[source]

Create a new contact record asynchronously.

POST /api/v2/contacts/new_contact

Parameters:

  • name (str)

  • address (list[dict[str, str]])

  • phone (list[dict[str, str] | None] | None)

  • email (list[dict[str, str] | None] | None)

  • contact_type (Literal['individual', 'organization'] | None)

  • kwargs (Unpack[RequestParameters])

Return type:

tuple[Any, str | None]

async britecore_sdk.api.api_calls.v2.anew_mortgagee(property_id, **kwargs)[source]

Create a new mortgagee for a property asynchronously.

POST /api/v2/policies/new_mortgagee

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.anew_revision_contact(revision_id, contact_id, x_id=None, contact_role='namedInsured', **kwargs)[source]

Add or update a contact assignment on a revision asynchronously.

The workflow uses revision_id, contact_id, and contact_role to create or reuse an x_revisions_contact_id before updating the revision contact link. Returns the async aprocess_result(...) payload, invalidates cached policy reads on success, and accepts RequestParameters overrides.

Parameters:

  • revision_id (str) – The revision identifier.

  • contact_id (str) – The contact identifier to assign.

  • x_id (str | None) – Optional existing x_revisions_contact_id (creates new if not provided).

  • contact_role (Literal['namedInsured', 'addtlInterest', 'financeCompany', 'underwriter', 'driver'] | None) – The role for the contact assignment (default ‘namedInsured’).

  • **kwargs (Unpack[RequestParameters]) – Additional request parameters and cache invalidation settings.

Returns:

The processed result from the final update_revision_contact call.

Return type:

Any

Raises:

RuntimeError – Multiple conditions when ado_request returns None for any operation, or KeyError when contact_add_result missing ‘x_revisions_contact_id’ key.

async britecore_sdk.api.api_calls.v2.arate_revision(revision_id, **kwargs)[source]

Calculate a rate for a revision asynchronously.

POST /api/v2/policies/rate_revision

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.arate_risk(risk_id, **kwargs)[source]

Calculate a rate for a risk asynchronously.

POST /api/v2/policies/rate_risk

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_policy(policy_number=None, policy_id=None, revision_state=None, **kwargs)[source]

Retrieve top-level policy information asynchronously..

Parameters:

  • policy_number (str | None)

  • policy_id (str | None)

  • revision_state (str | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_policy_contact_info(policy_number, **kwargs)[source]

Retrieve named insured contact information for a policy.

POST /api/v2/policies/retrieve_policy

Parameters:
Return type:

list[Any]

async britecore_sdk.api.api_calls.v2.aretrieve_policy_ids(policy_number, **kwargs)[source]

Retrieve the active revision ID and primary property ID for a policy.

POST /api/v2/policies/retrieve_policy

Parameters:
Return type:

tuple[str, str]

async britecore_sdk.api.api_calls.v2.aretrieve_policy_snapshot(policy_number, snapshot_date, **kwargs)[source]

Retrieve a policy snapshot asynchronously.

POST /api/v2/policies/retrieve_policy_snapshot

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_policy_terms(policy_id='', policy_number='', **kwargs)[source]

Retrieve policy terms and revisions asynchronously.

POST /api/v2/policies/retrieve_policy_terms

Parameters:

  • policy_id (str | None)

  • policy_number (str | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_revision_details(revision_id, include_contact_details=True, **kwargs)[source]

Retrieve detailed revision information asynchronously.

POST /api/v2/policies/retrieve_revision_details

Parameters:

  • revision_id (str)

  • include_contact_details (bool | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_risk_details(risk_id, **kwargs)[source]

Retrieve risk details asynchronously.

POST /api/v2/policies/retrieve_risk_details

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.aretrieve_risks(revision_id, page=0, page_size=10, retrieve_remaining=True, order_by='name', risk_types=None, **kwargs)[source]

Retrieve paginated or filtered risks for a revision asynchronously.

POST /api/v2/policies/retrieve_risks

Parameters:

  • revision_id (str)

  • page (int | None)

  • page_size (int | None)

  • retrieve_remaining (bool | None)

  • order_by (str | None)

  • risk_types (list[str] | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.astore_mortgagee(property_contact_id, mortgagee_contact_id, **kwargs)[source]

Store mortgagee information for a property contact asynchronously.

POST /api/v2/policies/store_mortgagee

Parameters:

  • property_contact_id (str)

  • mortgagee_contact_id (str)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aupdate_contact(contact, **kwargs)[source]

Update an existing contact asynchronously.

POST /api/v2/contacts/update_contact

Parameters:
Return type:

Any

async britecore_sdk.api.api_calls.v2.aupdate_property_location(location, soft_geoservice_bypass=None, hard_geoservice_bypass=None, reset_premiums=None, **kwargs)[source]

Update property location details asynchronously.

POST /api/v2/policies/update_property_location

Parameters:

  • location (dict[str, Any])

  • soft_geoservice_bypass (bool | None)

  • hard_geoservice_bypass (bool | None)

  • reset_premiums (bool | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

async britecore_sdk.api.api_calls.v2.aupdate_rating_information(property_id='', revision_id='', items=None, reset_premium=True, **kwargs)[source]

Update rating information for a revision or property asynchronously.

POST /api/v2/policies/update_rating_information

Parameters:

  • property_id (str | None)

  • revision_id (str | None)

  • items (list[dict[str, Any]] | None)

  • reset_premium (bool | None)

  • kwargs (Unpack[RequestParameters])

Return type:

Any

Workflow package exports

Higher-level workflow helpers for the BriteCore SDK.

This package provides both staged workflow helpers that orchestrate dependent object creation and batch helpers for bulk parallel operations.

Staged workflow helpers

Execute creation workflows in dependency order:

Contacts → Quotes → Policies/Revisions → Risks

Within each stage, items run concurrently with bounded concurrency.

  • britecore_sdk.api.workflows.staged_creation — synchronous staged workflow helper using ThreadPoolExecutor

  • britecore_sdk.api.workflows.async_staged_creation — asynchronous staged workflow helper using asyncio

Batch helpers

Domain-scoped parallel bulk-create helpers:

  • britecore_sdk.api.workflows.batch_contacts / britecore_sdk.api.workflows.async_batch_contacts — bulk contact creation

  • britecore_sdk.api.workflows.batch_policies / britecore_sdk.api.workflows.async_batch_policies — bulk policy and risk creation

  • britecore_sdk.api.workflows.batch_quotes — bulk quote creation via ThreadPoolExecutor

  • britecore_sdk.api.workflows.async_batch_quotes — bulk quote creation via asyncio

All public helpers are re-exported from this package for convenience:

from britecore_sdk.api.workflows import create_entities_staged_batch
from britecore_sdk.api.workflows import create_contacts_batch
from britecore_sdk.api.workflows import create_policies_batch
from britecore_sdk.api.workflows import create_risks_batch
from britecore_sdk.api.workflows import create_full_quotes_batch
from britecore_sdk.api.workflows import acreate_full_quotes_batch

See docs/STAGED_WORKFLOWS.md, docs/BATCH_QUOTE_CREATION.md, and the examples/ directory for usage and tuning guidance.

class britecore_sdk.api.workflows.BatchContactCreateResult[source]

Bases: TypedDict

Per-item outcome for create_contacts_batch.

index: int
success: bool
contact_data: dict[str, Any] | None
contact_id: str | None
error: str | None
class britecore_sdk.api.workflows.BatchPolicyCreateResult[source]

Bases: TypedDict

Per-item outcome for create_policies_batch.

index: int
success: bool
policy_data: dict[str, Any] | None
revision_id: str | None
error: str | None
class britecore_sdk.api.workflows.BatchQuoteCreateResult[source]

Bases: TypedDict

Per-item outcome for create_full_quotes_batch.

index: int
success: bool
quote_data: dict[str, Any] | None
quote_id: str | None
error: str | None
class britecore_sdk.api.workflows.BatchRiskCreateResult[source]

Bases: TypedDict

Per-item outcome for create_risks_batch.

index: int
success: bool
risk_data: dict[str, Any] | None
risk_id: str | None
error: str | None
class britecore_sdk.api.workflows.StagedWorkflowJob[source]

Bases: TypedDict

Input descriptor for a single end-to-end entity creation job.

All stage payloads are optional; omit a payload to skip that stage for this job. When contact_payload is present, the created contact_id is made available for subsequent stages.

Fields

contact_payload:

Keyword arguments for new_contact. Required keys: name (str), address (list[dict]). Optional: phone, email, contact_type.

quote_payload:

Full quote payload dict forwarded to create_full_quote.

policy_payload:

Keyword arguments forwarded to create_policy.

risk_payloads:

List of risk payload dicts, each forwarded to create_risk. revision_id is injected automatically when omitted.

contact_payload: dict[str, Any]
quote_payload: dict[str, Any]
policy_payload: dict[str, Any]
risk_payloads: list[dict[str, Any]]
class britecore_sdk.api.workflows.StagedWorkflowResult[source]

Bases: TypedDict

Per-job outcome returned by create_entities_staged_batch.

index: int
success: bool
contact_id: str | None
contact_data: dict[str, Any] | None
quote_id: str | None
quote_data: dict[str, Any] | None
revision_id: str | None
policy_data: dict[str, Any] | None
risk_ids: list[str]
risk_results: list[Any]
error: str | None
failed_stage: str | None
async britecore_sdk.api.workflows.acreate_contacts_batch(contacts_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Create many contacts concurrently and return per-item outcomes.

This helper runs anew_contact(...) with bounded concurrency so high-volume contact creation jobs complete much faster than fully serial execution. Each payload dict must include name and address keys (matching anew_contact parameters).

Parameters:

  • contacts_json (list[dict[str, Any]]) – List of contact payload dicts. Each dict must contain at minimum name (str) and address (list[dict]). Optional keys phone, email, and contact_type are forwarded if present.

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 5.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each contact create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchContactCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If contacts_json is missing/empty.

  • ValueError – If max_concurrent is less than 1.

  • Exception – First worker exception when fail_fast=True.

async britecore_sdk.api.workflows.acreate_entities_staged_batch(jobs, *, contact_max_concurrent=5, quote_max_concurrent=5, policy_max_concurrent=3, risk_max_concurrent=3, fail_fast=False, **kwargs)[source]

Create contacts, quotes, policies, and risks in a staged async batch workflow.

Async counterpart to create_entities_staged_batch(). Stages execute sequentially in dependency order; within each stage all pending items run concurrently bounded by asyncio.Semaphore.

Stages:

  1. Contacts — anew_contact (optional per job)

  2. Quotes — acreate_full_quote (optional per job)

  3. Policies — acreate_policy (optional per job; produces revision_id used by the risks stage)

  4. Risks — acreate_risk (optional per job; uses revision_id from Stage 3 when not supplied)

Parameters:

  • jobs (list[StagedWorkflowJob]) – List of StagedWorkflowJob dicts describing one end-to-end creation per element.

  • contact_max_concurrent (int) – Max concurrent coroutines for contacts stage. Defaults to 5.

  • quote_max_concurrent (int) – Max concurrent coroutines for quotes stage. Defaults to 5.

  • policy_max_concurrent (int) – Max concurrent coroutines for policies stage. Defaults to 3.

  • risk_max_concurrent (int) – Max concurrent coroutines for risks stage. Defaults to 3.

  • fail_fast (bool) – When True, raises the first stage exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters forwarded to every API call.

Returns:

  • total: total number of input jobs

  • succeeded: jobs with all requested stages successful

  • failed: jobs that encountered at least one error

  • stage_totals: dict keyed by stage name with total, succeeded, failed sub-dicts

  • results: list of StagedWorkflowResult ordered by input index

Return type:

dict[str, Any]

Raises:
async britecore_sdk.api.workflows.acreate_full_quotes_batch(quotes_json, max_concurrent=5, fail_fast=False, **kwargs)[source]

Create many quotes concurrently and return per-item outcomes.

This helper runs acreate_full_quote(...) with bounded concurrency so high-volume quote creation jobs can complete much faster than fully serial execution. It returns a stable, index-aligned result list with success/error metadata for each submitted payload.

Parameters:

  • quotes_json (list[dict[str, Any]]) – List of quote payload dictionaries.

  • max_concurrent (int) – Maximum concurrent coroutines. Defaults to 5.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each quote create call.

Returns:

  • total: total submitted quote payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchQuoteCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If quotes_json is missing/empty.

  • ValueError – If max_concurrent is less than 1.

  • Exception – First worker exception when fail_fast=True.

async britecore_sdk.api.workflows.acreate_policies_batch(policies_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Create many policies concurrently and return per-item outcomes.

This helper runs acreate_policy(...) with bounded concurrency so high-volume policy creation jobs complete much faster than fully serial execution. Each payload dict is unpacked as keyword arguments to acreate_policy.

Parameters:

  • policies_json (list[dict[str, Any]]) – List of policy payload dicts forwarded as kwargs to acreate_policy.

  • max_concurrent (int) – Maximum concurrent coroutines. Default is 3 (conservative because each policy create triggers heavy backend work).

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each policy create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchPolicyCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If policies_json is missing/empty.

  • ValueError – If max_concurrent is less than 1.

  • Exception – First worker exception when fail_fast=True.

async britecore_sdk.api.workflows.acreate_risks_batch(risks_json, max_concurrent=3, fail_fast=False, **kwargs)[source]

Create many risks concurrently and return per-item outcomes.

This helper runs acreate_risk(...) with bounded concurrency so high-volume risk creation jobs complete much faster than fully serial execution. Each payload dict must include revision_id; optional keys property_group_number, building_number, and force_categories are forwarded if present.

Parameters:

  • risks_json (list[dict[str, Any]]) – List of risk payload dicts forwarded as kwargs to acreate_risk.

  • max_concurrent (int) – Maximum concurrent coroutines. Default is 3.

  • fail_fast (bool) – When True, raises the first encountered exception and cancels remaining tasks. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each risk create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchRiskCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If risks_json is missing/empty.

  • ValueError – If max_concurrent is less than 1.

  • Exception – First worker exception when fail_fast=True.

britecore_sdk.api.workflows.create_contacts_batch(contacts_json, max_workers=5, fail_fast=False, **kwargs)[source]

Create many contacts concurrently and return per-item outcomes.

This helper runs new_contact(...) in a bounded thread pool so high-volume contact creation jobs complete much faster than fully serial execution. Each payload dict must include name and address keys (matching new_contact parameters).

Parameters:

  • contacts_json (list[dict[str, Any]]) – List of contact payload dicts. Each dict must contain at minimum name (str) and address (list[dict]). Optional keys phone, email, and contact_type are forwarded if present.

  • max_workers (int) – Maximum concurrent workers. Defaults to 5.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each contact create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchContactCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If contacts_json is missing/empty.

  • ValueError – If max_workers is less than 1.

  • Exception – First worker exception when fail_fast=True.

britecore_sdk.api.workflows.create_entities_staged_batch(jobs, *, contact_max_workers=5, quote_max_workers=5, policy_max_workers=3, risk_max_workers=3, fail_fast=False, **kwargs)[source]

Create contacts, quotes, policies, and risks in a staged batch workflow.

Stages execute in dependency order; within each stage all pending items run concurrently with bounded workers. Stages are:

  1. Contacts — new_contact (optional per job)

  2. Quotes — create_full_quote (optional per job)

  3. Policies — create_policy (optional per job; produces revision_id used by the risks stage)

  4. Risks — create_risk (optional per job; uses revision_id from Stage 3 when not supplied)

Any job that fails a stage is excluded from subsequent stages. When fail_fast=True the first failure re-raises immediately; otherwise failures are captured per item and processing continues.

Parameters:

  • jobs (list[StagedWorkflowJob]) – List of StagedWorkflowJob dicts describing one end-to-end creation per element.

  • contact_max_workers (int) – Max concurrent workers for the contacts stage. Defaults to 5.

  • quote_max_workers (int) – Max concurrent workers for the quotes stage. Defaults to 5.

  • policy_max_workers (int) – Max concurrent workers for the policies stage. Defaults to 3 (conservative; each policy create is heavy).

  • risk_max_workers (int) – Max concurrent workers for the risks stage. Defaults to 3.

  • fail_fast (bool) – When True, re-raises the first stage exception and cancels remaining futures. Defaults to False.

  • **kwargs (Any) – RequestParameters forwarded to every API call.

Returns:

  • total: total number of input jobs

  • succeeded: jobs with all requested stages successful

  • failed: jobs that encountered at least one error

  • stage_totals: dict keyed by stage name with total, succeeded, failed sub-dicts

  • results: list of StagedWorkflowResult ordered by input index

Return type:

dict[str, Any]

Raises:
britecore_sdk.api.workflows.create_full_quotes_batch(quotes_json, max_workers=5, fail_fast=False, **kwargs)[source]

Create many quotes concurrently and return per-item outcomes.

This helper runs create_full_quote(...) in a bounded thread pool so high-volume quote creation jobs can complete much faster than fully serial execution. It returns a stable, index-aligned result list with success/error metadata for each submitted payload.

Parameters:

  • quotes_json (list[dict[str, Any]]) – List of quote payload dictionaries.

  • max_workers (int) – Maximum concurrent workers. Defaults to 5.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each quote create call.

Returns:

  • total: total submitted quote payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchQuoteCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If quotes_json is missing/empty.

  • ValueError – If max_workers is less than 1.

  • Exception – First worker exception when fail_fast=True.

britecore_sdk.api.workflows.create_policies_batch(policies_json, max_workers=3, fail_fast=False, **kwargs)[source]

Create many policies concurrently and return per-item outcomes.

This helper runs create_policy(...) in a bounded thread pool so high-volume policy creation jobs complete much faster than fully serial execution. Each payload dict is unpacked as keyword arguments to create_policy; at minimum policy_number and policy_type_id are typically required.

Parameters:

  • policies_json (list[dict[str, Any]]) – List of policy payload dicts. Each dict is forwarded as keyword arguments to create_policy.

  • max_workers (int) – Maximum concurrent workers. Default is 3 (conservative because each policy create triggers heavy backend work).

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each policy create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchPolicyCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If policies_json is missing/empty.

  • ValueError – If max_workers is less than 1.

  • Exception – First worker exception when fail_fast=True.

britecore_sdk.api.workflows.create_risks_batch(risks_json, max_workers=3, fail_fast=False, **kwargs)[source]

Create many risks concurrently and return per-item outcomes.

This helper runs create_risk(...) in a bounded thread pool so high-volume risk creation jobs complete much faster than fully serial execution. Each payload dict must include a revision_id key; optional keys property_group_number, building_number, and force_categories are forwarded if present.

Parameters:

  • risks_json (list[dict[str, Any]]) – List of risk payload dicts. Each dict must contain at minimum revision_id (str).

  • max_workers (int) – Maximum concurrent workers. Default is 3.

  • fail_fast (bool) – When True, re-raises the first encountered exception and cancels pending futures. Defaults to False.

  • **kwargs (Any) – RequestParameters passed through to each risk create call.

Returns:

  • total: total submitted payload count

  • succeeded: number of successful creates

  • failed: number of failed creates

  • results: list[BatchRiskCreateResult] ordered by input index

Return type:

dict[str, Any]

Raises:

  • BritecoreError.MissingParameter – If risks_json is missing/empty.

  • ValueError – If max_workers is less than 1.

  • Exception – First worker exception when fail_fast=True.

API Domains

Browse grouped endpoint docs from the dedicated domains page: