Cancellations

A cancellation is a policy transaction that terminates an existing policy prior to its expiration date. This topic covers how to manage cancellations through Cloud API.

For details on the business functionality of cancellations, see the Application Guide.

Initiating a cancellation

Cancellations are initiated from the policy itself. Use the following endpoint to create a cancellation for a given policy:

  • POST /policy/v1/policies/{policyId}/cancel

You must specify the following fields:

  • cancellationReasonCode: A typecode from the ReasonCode typelist
  • cancellationSource: A typecode from the CancellationSource typelist
  • jobEffectiveDate: A date

For example, the following initiates a cancellation for policy pc:44.

POST /policy/v1/policies/pc:44/cancel
                
{
  "data": {
    "attributes": {
      "cancellationReasonCode": {
        "code": "cancel"
      },
      "cancellationSource": {
        "code": "carrier"
      },
      "jobEffectiveDate": "2020-08-15"
    }
  }
}

This call creates a new job instance whose job type is "Cancellation". The job's state is Quoted.

Modifying and requoting the cancellation

Typically, a policy is not modified when it is canceled. The most common intent of a cancellation is to cancel the policy in its current state.

However, it is technically possible to modify the contents of a policy within a cancellation prior to binding the cancellation.

  • Before the job can be changed, the renewal's job must be set to "Draft". To do this, use the POST /job/v1/jobs/{jobId}/make-draft endpoint, which reverts the job's status to "Draft".
  • Once the job has been changed, it must be requoted. To do this, use the POST /job/v1/jobs/{jobId}/quote endpoint.

Completing the cancellation

The following table summarizes the different endpoints that can be used to complete a cancellation.

Outcome Endpoint
Cancel the policy now /job/v1/jobs/{jobId}/bind-and-issue
Schedule a cancellation for a future date /job/v1/jobs/{jobId}/pending-cancel
Change the process date for a scheduled cancellation /job/v1/jobs/{jobId}/reschedule
Rescind a scheduled cancellation /job/v1/jobs/{jobId}/rescind
Withdraw the cancellation /job/v1/jobs/{jobId}/withdraw

Example of binding the cancellation immediately

Use the following endpoint to bind a cancellation immediately:

  • POST /job/v1/jobs/{jobId}/bind-and-issue

The request object does not require a request body.

For example, the following request binds and issues job pc:333.

POST /job/v1/jobs/pc:333/bind-and-issue
                
<no request body>

The cancellation's status is changed to "Bound".

Example of withdrawing a cancellation

Use the following endpoint to withdraw the cancellation:

  • POST /job/v1/jobs/{jobId}/withdraw

The request object does not require a body.

For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw
                
<no request body>

The cancellation's status is changed to "Withdrawn".