Endorsements

Endorsements are used to change all policy, exposure, and peril details, with options for repricing the endorsed period of the policy.

Endorsement objects contain instructions for how the policy should change. These changes can include:

  • Updating field values at the policy, exposure, and peril levels

  • Adding and ending exposures

  • Adding and ending perils

  • Changes to the end time of the policy

  • Optional repricing of the endorsed period

Changes made in an endorsement are carried forward until the end of the policy.

See the Endorsements API topic for information about how to implement this feature.

Note

Further important information about endorsement lifecycle and pricing can be found in Policy Change Management.

Repricing

Repricing runs the premium, tax and commissions calculations and applies them to the endorsed period of the policy. Premium is allocated to periods before the endorsed period of the policy on a pro-rata basis. Future invoices are unaffected if the endorsement does not result in a reprice.

In configuration, the reprice setting takes one of four values: never, always, all or input. If omitted, reprice defaults to never.

  • The input option requires that the user or API call specify what to do and otherwise returns an error. In the API, this is done by passing in true or false on the reprice parameter.

  • The always option means that the period after the endorsement will always be repriced using the premium calculation logic if its field values have changed.

  • The all option means that the period after the endorsement will be repriced even if none of its data has changed.

  • The never option means that the period will be prorated and pricing logic will not be invoked.

Endorsement Types

Multiple endorsement types may be created, and the user can choose from among them when endorsing. Each endorsement type can have different documents generated upon acceptance.

Extensions and Reductions

The policy end can be changed along with any other changes in the endorsment. Updated end times must be at midnight in the tenant’s timezone. The change to the end will be reflected in the effectiveContractEndTimestamp in the PolicyResponse.

If the endorsement only changes the policy end time, Socotra will automatically set the effective time of the endorsement to the earlier of the old and new end times. The user may not specify the start time of the endorsement.

Policies are extended when the policy end is made later than before:

  • Any coverage active at the current end time of the policy will be extended

  • Extended coverage will be priced using the peril’s premium calculation

Policies are reduced when the policy end is made earlier than before:

  • All coverage will be terminated as of the new end time

  • Refunds will be prorated

Configuration

The file policy/endorsements.json specifies names for the endorsements that may be applied to a policy. If this file is empty or doesn’t exist, endorsements will be disabled for that product. Documents to be generated along with the endorsement are optionally specified here.

Example endorsements.json

{
  endorsements: [
    {
      name: "change.address",
      displayName: "Change Address",
      reprice: "always",
      documents: [
        {
          displayName: "Address Change",
          fileName: "address_endt.pdf",
          templateName: "address_endt.template.liquid",
          generatingEvent: "accept"
        }
      ]
    },
    {
      name: "change.beneficiary",
      displayName: "Change Beneficiary"
    }
  ]
}

Endorsement Documents

You may configure any number of documents to be generated with an endorsement. The same document template may be used for multiple endorsements, or each may have a dedicated template, as specifed in the configuration. These templates have access to the same data available to other Document Templates, as well as data.endorsement:

data.endorsement: {
  name: string,
  locator: locator,
  display_id: string,
  start_timestamp: timestamp, /* optional */
  issued_timestamp: timestamp,
  effective_contract_end_timestamp: timestamp,
  repriced: boolean,
  price: PolicyPriceChange,
  policy_updates: {
    locator: locator,
    display_id: string,
    all_exposures: map<ExposureName, [EndorsedExposure]>,
    updated_exposures: map<ExposureName, [EndorsedExposure],
    all_field_values: map<FieldName, [EndorsedFieldValue],
    updated_field_values: map<FieldName, [EndorsedFieldValue],
    all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
    updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
  }

  // Deprecated fields (use policy_updates instead of these)
  field_values: map<string, string[]>
  add_field_groups: [FieldGroupCreateRequest],
  update_field_groups: [FieldGroupUpdateRequest],
  remove_field_groups: [string],
  update_exposures: [ExposureUpdate]
}

EndorsementEffect: One of "unchanged", "added", "removed", or "updated"

EndorsedFieldValue: {
  title: string,
  endorsement_effect: EndorsementEffect,
  old_value: string | [string],
  new_value: string | [string]
}

EndorsedFieldGroup: {
  locator: string,
  title: string,
  endorsement_effect: EndorsementEffect,
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>
}

EndorsedExposure: {
  locator: locator,
  display_id: string,
  name: ExposureName,
  display_name: string,
  endorsement_effect: EndorsementEffect,
  all_perils: map<PerilName, [EndorsedPeril],
  updated_perils: map<PerilName, [EndorsedPeril],
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>,
  all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
  updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
}

EndorsedPeril: {
  locator: locator,
  display_id: string,
  name: PerilName,
  display_name: string,
  endorsement_effect: EndorsementEffect,
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>,
  all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
  updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
}

PolicyPriceChange: {
  new_total: number,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_fees: number,
  new_gross_commissions: number,
  total_change: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_fees_change: number,
  gross_commissions_change: number,
  exposure_prices: ExposurePriceChange,
  tax_groups: [PricedTax],
  fees: [PricedFee]
  commissions: [PricedCommission]
}

ExposurePriceChange: {
  locator: locator,
  name: string,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_commissions: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_commissions_change: number,
  peril_prices: [PerilPriceChange],
  tax_groups: [PricedTax],
  commissions: [PricedCommission]
}

PerilPriceChange: {
  locator: locator,
  name: string,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_commissions: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_commissions_change: number,
  peril_prices: [PerilPriceChange],
  taxes: [PricedTax],
  commissions: [PricedCommission]
}

PricedTax: {
  name: string,
  new_amount: number,
  change: number
}

PricedFee: {
  locator: locator,
  name: string,
  new_amount: number,
  amount_change: number
}

PricedCommission: {
  new_amount: number,
  amount_change: number,
  recipient: string
}