Cancel a policy
In an agent portal, agents can cancel an existing policy.
Agents cancel policies by processing a Cancellation Notice transaction followed by a Cancellation transaction. Or, agents can cancel a policy by directly processing a Cancellation transaction.
Processing a cancellation transaction includes the following steps:
- Identify the policy transaction.
- Gather the cancellation details.
- Submit and process the Cancellation.
Note: The Cancellation Notice process is the same as the Cancellation process except that
the
transactioncd
is different. Identify the policy transaction
Initiating a cancellation starts with an agent deciding to create a new transaction on a policy.
Then, agent portal calls an API to determine the types of transactions that are valid for a
policy.

Once an agent selects the Cancellation transaction, the agent portal must note the code value of the transaction as it is required to request the transaction in a later step.
For example, the following steps may occur:- View the policy details:
- The portal submits the following API
call:
GET /policies/systemid
- The portal displays the policy details provided in the response.
- The portal submits the following API
call:
- View the list of available transactions:
- The portal submits the following API call:
GET /policies/systemid/availableTransactions
- The portal provides the user a list of available transactions based on the API response.
- The agent selects the Cancellation transaction.
- From the API response, the portal notes the value of the
Cancellation option.
[ ... "value": "Cancellation", "name": "Cancellation" }, { "value": "Endorsement", "name": "Endorsement" }, ... ]
- The portal submits the following API call:
Gather the cancellation details
Before an agent portal can submit a Cancellation transaction request, the agent portal
needs to gather the following details:
- requestedByCd
- The agent portal calls the following API to determine valid
requestedByCd
values:
GET /coderefs/UWPolicy/policy/transaction/cancel-requested-by
- reasonCd
- The agent portal calls the following API to determine the cancellation reason codes
that are valid for a policy:
GET /policies/systemId/transactionReasons/cancelRequestedByCd
- cancellationType
- The agent portal calls the following API to determine the cancellation types that
are valid for a policy:
GET /policies/systemId/cancallationType/reasonCd
Submit and process the Cancellation transaction request
Submitting and processing a cancellation starts with the agent portal calling an API to
initiate a cancellation request. Then, the system creates an application and the agent
processes the application.

For example, the following steps may occur:
- Start the cancel transaction request:
- The portal executes the following API request:
Endpoint POST /policies/systemId/startCancellationTransactionRequest
Example Request Body { "transactionCd": "Cancellation", "requestedByCd": "Insured", "reasonCd": "InsuredRequest", "effectiveDate": "2021-05-22", "cancellationType": "Pro-Rate" }
Provide the
value
of the Cancellation transaction as the transactionCd.Note: The other values will differ based on agent selections.Note: If the Cancellation transaction follows a Cancellation Notice on the policy, the values provided in the request body of the Cancellation transaction must match those provided in the Cancellation Notice transaction. You can view the details of any existing Cancellation Notice transaction in the API response ofGET /policies/systemid
. - From the API response, note the systemID of the application in
the location
header:
... location: https://hostname/coreapi/v5/applications/systemID ...
- The portal executes the following API request:
- View the new application
- The portal executes the following API
call:
GET /applications/systemid
- The portal displays the application details provided in the API response.
- The agent completes the application.
- The portal executes the following API
call: