The Create and bind a quote tutorial walks you through the inception of a policy in BriteCore. It also describes how different services in BriteCore work together in creating a new policy. In Retrieve and display policy information, we cover more information on how policies are managed in BriteCore. The most important thing to note is that while BritePolicies APIs act as a hub for all policy-related information, it's the BriteQuote APIs that handle all policy transaction services. This tutorial will walk you through the BriteQuote API endpoints that handle policy transactional services, including:

• Creating or updating endorsements.
• Deleting endorsements.
• Canceling a policy.
• Reinstating a cancellation.

We will cover some key concepts, policy transactions in BriteCore, the policy lifecycle, and the endorsements process flow. We also highlight which API endpoints to use for each transaction.

Key concepts

• Cancellation: A coverage no longer in effect.
• Cancellation pending: Increase in risk/failure to pay on time.
• Commit date: The date the revision (or endorsement) is put into force.
• Coverage: A guarantee of financial restoration in the event of a loss.
• Endorsement: A change to a policy, such as increasing coverage, decreasing coverage, or changing the mortgagee. Within BriteCore, endorsements are referred to as revisions.
• Endorsement transactions: Revisions to the in-force policies.
• Effective date: The date an insurance policy becomes active.
• Expiration: End of the term without a renewal offer.
• In-force policies: Insurance policies that are currently under contract.
• Non-renewal: No offer to extend coverage for another term.
• Policy: A contract that guarantees insurance coverage for a given duration of time.
• Premium: Money paid by a policyholder to an insurance carrier in exchange for insurance.
• Reinstatement: Previously canceled coverage is now back in effect.
• Renewal: An offer to extend coverage for another term.
• Revision: A BriteCore-specific term that refers to a point-in-time snapshot of the policy contract created when there is a substantive change to the contract. Within BriteCore, endorsements are referred to as revisions.
• Risk: An asset protected by insurance.
• State: Describes a step in a particular transactional workflow process, such as In progress, Approved, Rejected, or Abandoned.
• Status: The current status of the policy contract in relation to specific workflows, such as Active, Canceled, and Expired.
• Transaction: A point-in-time action that results in a document exchange among parties, such as agents, insureds, and underwriters. Not every transaction is a revision.
• Straight-through processing: Electronically streamline and process information across multiple points.

Policy transactions in BriteCore

Table 1 summarizes the policy transactions in BriteCore with their states, status, and related documents.

Table 1: Policy transactions.

Policy lifecycle APIs

This article replaces the legacy Help Center entry on endorsing, renewing, canceling, and reinstating policies (https://help.britecore.com/hc/en-us/articles/8723309089683-Endorse-renew-cancel-and-reinstate-your-policy). It consolidates the controls that now live in BriteCore's v2 APIs so that you can promote lifecycle changes without relying on UI flows.

Prerequisites

• Use the /api/v2 base path and authenticate every request with an api_key plus the headers shown in the Bruno samples below.
• Know the identifiers you will pass: policy_id, policy_term_id, quote_id, or external references, along with the revision effective date you want to manipulate.
• Run the same validation the UI would perform by calling POST /api/v2/policies/review_revision (Straight-Through Processing/STP) before issuing a change, even if it is optional.
• All lifecycle actions eventually commit a revision, so plan follow-up deliverables (decs, invoices, tasks) that downstream systems expect.

Endorse a policy

1. Clone the in-force revision by calling POST /api/v2/quotes/create_endorsement_quote. Supply either the existing quote_id or its external reference plus the endorsement_date. The endpoint returns a fully-hydrated quote that is safe to modify.
2. Update the quote with POST /api/v2/quotes/modify_full_quote (or the granular items, risks, underwriting endpoints, if you prefer). You can rate and retrieve the quote as many times as needed.
3. Validate and commit once the change is ready:
   • Run STP by posting the endorsement revision_id to /api/v2/policies/review_revision.
   • Issue the quote with POST /api/v2/quotes/issue_full_quote to move the revision into the committed state and trigger deliverables.

Reference payloads

post {
  url: {{url}}/api/v2/quotes/create_endorsement_quote
  body: json
  auth: inherit
}

body:json {
  {
      "api_key": "{{apiKey}}",
      "quote_id": "{{quoteId}}",
      "endorsement_date": "10-15-2025"
   }
}

{
  "$id": "BritecoreCreateEndorsementQuoteRequest.v1",
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "format": "uuid"
    },
    "quote_external_system_reference": {
      "type": "string"
    },
    "endorsement_date": {
      "type": "string",
      "format": "date"
    }
  },
  "oneOf": [
    { "required": ["quote_id"] },
    { "required": ["quote_external_system_reference"] }
  ]
}

post {
  url: {{url}}/api/v2/quotes/modify_full_quote
  body: json
  auth: inherit
}

body:json {
  {
      "api_key": "{{apiKey}}",
      "policy_type_id": "{{policyTypeId}}",
      "effective_date": "2024-12-20",
      "term_type": "Custom",
      "expiration_date": "2025-11-20",
      "renewal_type": "6 Months",
      "agency_id": "09144aa9-c83c-43bf-8313-2736b2723468",
      "named_insureds": [
        {
              "name": "James Bond2",
              "type": "individual",
              "addresses": [{
                  "city": "Sand Francisco",
                  "street": "1234 Main St",
                  "state": "CA",
                  "zipcode": "94111",
                  "is_preferred": true,
                  "type": "Mailing/Billing"
              }],
              "is_primary": true
          }
      ],
      "billing_information": {
          "billing_schedule": "Annual"
      }
  }
}

Renew a policy

POST /api/v2/quotes/create_renewal_quote creates the next-term revision from the latest committed (or pending) revision. You can identify the policy by quote_id, external_system_reference, or policy_number; the API enforces that at least one of those identifiers is present and that you only renew from the latest revision before handing you another full-quote payload to modify, rate, review, and issue.

@api_request()
def create_renewal_quote(quote_id=None, external_system_reference=None, policy_number=None):
    """
    Create a renewal quote using the latest committed or pending revision.
    Request:
        - Quote ID or Quote Exref or Policy Number.
    Response:
        - Full Quote response.
    Validations:
        - Renewal can only be created on the latest committed or pending revision.
    """
    if not (quote_id or external_system_reference or policy_number):
        raise BCGlobalValidationError(
            "At least one identifier (quote_id, external_system_reference, or policy_number) must be provided.")
    renewal_revision = quote_service.create_renewal_quote(
        quote_id=quote_id,
        external_system_reference=external_system_reference,
        policy_number=policy_number
    )
    return CreateFullQuoteResponseModel().serialize(renewal_revision)

{
  "$id": "BritecoreCreateRenewalQuote.v1",
  "type": "object",
  "properties": {
    "quote_id": { "type": "string", "format": "uuid" },
    "external_system_reference": { "type": "string" },
    "policy_number": { "type": "string" }
  },
  "oneOf": [
    { "required": ["quote_id"] },
    { "required": ["external_system_reference"] },
    { "required": ["policy_number"] }
  ]
}

Once the renewal quote exists, follow the same modify → rate → review → issue sequence used for endorsements so that the renewal commits and delivers documents/invoices.

Cancel a policy

POST /api/v2/policies/cancel_policy_v2 is the modern cancellation endpoint. It validates identifiers, enforces date formatting, supports idempotency, and returns a standard structure with the resulting revision, status, and descriptions. Supply the policy, the specific term (by UUID or external reference), a cancellation reason (either *_id or literal string), and the effective date. Optionally include a pending date, print description, or internal notes.

@api_request(unpack_payload=False)
@requires_permission('britecore/policies/cancelPolicy', PermissionLevelRule.READ_WRITE_ACCESS)
def cancel_policy_v2(
    request_params
):
    """
    Enhanced API v2 endpoint for policy cancellation with comprehensive validation and error handling.
    ...
    """
    policy_cancellation_schema = CancelPolicyRequestSchema()
    request_data = policy_cancellation_schema.deserialize(request_params)

    service = PolicyService()

    result = service.cancel_policy(request_data)

    response_schema = CancelPolicyResponseSchema()
    return response_schema.serialize(result)

{
  "$id": "CancelPolicyRequest.v2",
  "type": "object",
  "properties": {
    "policy_id": { "type": "string", "format": "uuid" },
    "policy_term_id": { "type": "string", "format": "uuid" },
    "policy_term_external_system_reference": { "type": "string" },
    "cancellation_reason_id": { "type": "string", "format": "uuid" },
    "cancellation_reason": { "type": "string" },
    "cancellation_date": { "type": "string", "format": "date" },
    "cancellation_pending_date": { "type": "string", "format": "date" },
    "print_description": { "type": "string", "maxLength": 2000 },
    "additional_description": { "type": "string", "maxLength": 5000 }
  },
  "required": [
    "policy_id",
    "cancellation_date"
  ],
  "allOf": [
    { "oneOf": [ { "required": ["policy_term_id"] }, { "required": ["policy_term_external_system_reference"] } ] },
    { "oneOf": [ { "required": ["cancellation_reason_id"] }, { "required": ["cancellation_reason"] } ] }
  ]
}

post {
  url: {{url}}/api/v2/policies/cancel_policy_v2
  body: json
  auth: inherit
}

body:json {
  {
    "api_key": "{{apiKey}}",
    "policy_id": "{{policyId}}",
    "policy_term_id": "{{policyTermId}}",
    "cancellation_reason": "Property Sold",
    "cancellation_date": "2025-08-13",
    "cancellation_pending_date": "2025-08-12",
    "print_description": "Policy cancelled due to change in policy type as requested by insured.",
    "additional_description": "Customer requested change from Homeowners to Condo policy. New policy will be issued under different policy number."
  }
}

Appendix: Supporting endpoints

These helper endpoints are reused across endorsements and renewals:

post {
  url: {{url}}/api/v2/policies/review_revision
  body: json
  auth: inherit
}

body:json {
  {
    "api_key": "{{apiKey}}",
    "revision_id": "{{revisionId}}"
  }
}

post {
  url: {{url}}/api/v2/quotes/issue_full_quote
  body: json
  auth: inherit
}

body:json {
  {
      "api_key": "{{apiKey}}",
      "id": "{{quoteId}}"
  }
}

Use them after every lifecycle action so that revisions pass STP and get committed consistently.