Policy renewal web services

The PolicyRenewalAPI handles policy renewal requests received from external systems. The service is located in the package gw.webservice.pc.VERSION.job.

Start renewals on existing policies

The startRenewals method of the PolicyRenewalAPI web service starts renewals on one or more existing PolicyCenter policies.

startRenewals(policyNumbers : String[])

The policyNumbers argument is an array of policy numbers that reference existing policies in PolicyCenter. If a referenced policy does not exist in PolicyCenter, a BadIdentifierException is thrown and any subsequent policies in the array are not processed.

The method has no return value.

The method starts a renewal job for each referenced policy. The entries in policyNumbers are processed in sequence. When a successful renewal is created, it is committed to the database. No gap in coverage exists between the original policy period and its renewal.

Import a policy for renewal

The startConversionRenewal method of the PolicyRenewalAPI web service starts a renewal for a single policy. The policy does not yet exist in PolicyCenter, but is imported from an external system as part of the method's renewal process.

startConversionRenewal(accountNumber : String,
                       productCode : String,
                       producerCodeId : String,
                       policyNumber : String,
                       policyPeriodData : String,
                       changesToApply : String,
                       parseOptions : String,
                       basedOnEffectiveDate : String,
                       basedOnExpirationDate : String) : String

The method accepts the following arguments.

  • accountNumber - Reference to an existing PolicyCenter account. If the account does not exist in PolicyCenter, a BadIdentifierException is thrown.
  • productCode - Reference to an existing PolicyCenter product code, such as PersonalAuto or WorkersComp. If the product does not exist, a BadIdentifierException is thrown.
  • producerCodeId - Reference to an existing PolicyCenter producer code. If the producer code does not exist, a BadIdentifierException is thrown.
  • policyNumber - The unique ID number to assign to the imported policy. If the argument is null or references an existing PolicyCenter policy, the method generates a new and unique policy ID number.
  • policyPeriodData - The policy period data to import. The String contents are parsed as XML that conforms to the PolicyCenter PolicyPeriodModel GX model. Load the GX model in Studio to view its structure.
  • changesToApply - Not used in the base configuration. Custom implementations can use the argument to reference settings in the renewal policy period that differ from the legacy imported period.
  • parseOptions - Not used in the base configuration. Custom implementations can use the argument for their own purposes.
  • basedOnEffectiveDate - The effective date of the legacy imported policy period.
  • basedOnExpirationDate - The expiration date of the legacy imported policy period. This date is also used as the effective date for the new imported renewal policy period. There is no gap in coverage between the legacy imported policy period and the renewal period.

If the accountNumber, productCode, or producerCodeId do not exist in PolicyCenter, the policy is not imported.

The imported policyPeriodData does not support attaching Note or Document objects to the renewal policy period. Note and Document objects can be attached to the renewal policy period after it has completed the renewal process.

The basedOnEffectiveDate value is passed to the Effective Time plugin's getConversionRenewalEffectiveTime method for processing.

The basedOnExpirationDate value is passed to the Effective Time plugin's getConversionRenewalExpirationTime method for processing.

The method creates a new policy on the specified account. Also, a new policy period is created and associated with the new policy. Finally, a renewal job is started for the new policy period. The renewal is in draft mode and is not bound. If the operation fails, the method throws a DataConversionException.

The method returns the renewal job's ID number as a String.

Policy renewal methods for billing systems

Billing systems use the PolicyRenewalAPI web service to send confirmation of renewals to PolicyCenter. Renewals can be configured to operate with or without renewal confirmation.

See also

Confirm a policy term

A billing system can notify PolicyCenter that an insured has confirmed a renewal. Confirmation usually takes the form of the insured submitting a payment for the renewal.

The confirmTerm method of the PolicyRenewalAPI web service confirms a policy term.

confirmTerm(policyNumber : String, termNumber : int, transactionId : String)

The method accepts the following arguments.

  • policyNumber - Specifies the number of the confirmed policy
  • termNumber - Specifies the number of the confirmed term
  • transactionId - Unique transaction ID to use for the bundle

The policyNumber and termNumber arguments cannot be null. They must reference a bound and unarchived policy term.

The method has no return value.

The method calls the IBillingSystemPlugin method updatePolicyPeriodConfirmed. In the base configuration, the plugin method sets the specified policy term's TermConfirmed field to true.

Notify PolicyCenter of receipt of payment for renewal

The notifyPaymentReceivedForRenewalOffer method of the PolicyRenewalAPI web service notifies PolicyCenter that the billing system has received payment for a renewal offer.

notifyPaymentReceivedForRenewalOffer(offerID : String,
                                     selectedPaymentPlanCode : String,
                                     paymentAmount : MonetaryAmount,
                                     transactionId : String) : String

The method accepts the following arguments.

  • offerID - Unique ID of the renewal offer. Cannot be null. The relevant policy period term must not be archived.
  • selectedPaymentPlanCode - Billing payment plan code
  • paymentAmount - Self explanatory
  • transactionId - Unique transaction ID to use for the bundle

If the relevant policy period term is already bound, the method returns the period's policy number.

The method creates an activity and returns null if any of the following conditions occur.

  • The policy is not in the correct state to accept the payment
  • An applicable payment plan as specified by the selectedPaymentPlanCode and paymentAmount arguments could not be found

Otherwise, the method invokes the active workflow trigger FinishIssueRenewal and returns the period's policy number.