Referral reasons

While a policy is in force, an insurer may become aware of information that has implications for the policy's renewal. This information may require underwriter approval, but at the time the renewal has not yet been started. Because there is no active job, the information cannot be captured as an underwriting issue.

To address these situations, PolicyCenter provides referral reasons. Like underwriting issues, a referral reason is an object that tracks an issue that may require underwriter review. However, referral reasons are attached only to policies. The next time a job is created for the policy, the referral reason may trigger the creation of an underwriting issue.

Querying for referral reasons

To request information about referral reasons associated with a policy, use the following endpoint:

  • GET /policy/v1/policies/{policyId}/uw-referral-reasons
  • GET /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}

Creating referral reasons

To create a referral reason, use the following endpoint:

  • POST /policy/v1/policies/{policyId}/uw-referral-reasons

Minimum creation criteria

At a minimum, a referral reason must specify:

  • The issue type (specified by the issue type's code)

Referral reasons use the same set of issue types as underwriting issues. Referral reasons created through Cloud API must have a checking set of Referral. For information on how to retrieve a list of issue types, see Minimum creation criteria.

As is the case with underwriting issues, some referral reasons require other values, depending on the issueType. For example:

  • For money referral reasons, a moneyValue object with amount and currency is required
  • For stateSet referral reasons, a stateSetValue object with inclusionType and states is required, and states must have one or more members.
  • The LegacyReferralReason issue type is explicitly disallowed by Cloud API.

The following fields are not required to create a referral reason. However, they are displayed in the user interface. Referral reasons that do not have these fields specified may be difficult to work with in the user interface.

  • A shortDescription (displayed when listing referral reasons)
  • A longDescription (displayed when providing details about referral reasons)

Example of creating a referral reason

The following code creates a referral reason for policy pc:707. The referral reason (ReferralBlockingQuote) will be used to create an underwriting issue that blocks quoting until an underwriter has reviewed the policy for potential fraud.

POST /policy/v1/policies/pc:707/uw-referral-reasons

{
  "data": {
    "attributes": {
        "issueType": {
            "code": "ReferralBlockingQuote"
        },
        "shortDescription": "Potential fraud",
        "longDescription": "Potential fraud - verify appraisal values for covered luxury items are accurate"
    }
  }
}

Closing and reopening referral reasons

For underwriting issues, you can resolve the issue and allow the job to move forward by either approving the issue or "special approving" the issue. For more information on underwriting issue approval, see Managing underwriting issue approval.

Referral reasons have a similar behavior. You can resolve a referral reason by either closing the reason or "special closing" the reason. In either case, PolicyCenter will not create an open underwriting issue from the referral reason when the next job is initiated.

Closing a referral reason

In most cases, a referral reason that is resolved is resolved by closing it. This action is equivalent to clicking the Close button on the Risk Analysis screen's UW Referral Reasons tab.

To close a referral reason through Cloud API, use the following endpoint:

  • POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/close

The /close endpoint does not require a request body. When you close a referral reason, the status is set to "Closed".

"Special closing" a referral reason

In rare cases, an underwriting issue is closed by special closing it. This action is equivalent to clicking the Special Close button on the Risk Analysis screen, which is visible only to users with the uwapproveall system permission.

To "special close" a referral reason through Cloud API, use the following endpoint:

  • POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/special-close

The /special-close endpoint does not require a request body. When you "special close" a referral reason, the status is set to "Closed".

Reopening a referral reason

To reopen a closed referral reason, use the following endpoint:

  • POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/reopen

The /reopen endpoint does not require a request body. When you reopen a closed referral reason, the status is set to "Open".