Request Cancellation
curl --request POST \
--url https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request \
--header 'AccessToken: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"effective_date_transaction": "03/01/2026",
"effective_date_transaction_al": "03/01/2026",
"effective_date_transaction_wc": "03/01/2026",
"cancellation_reason": [
"non_payment"
],
"internal_cancellation_reason": [
"<string>"
],
"cancellation_back_date_reason": "<string>",
"cancellation_back_date_reason_other": "<string>"
}
'import requests
url = "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request"
payload = {
"effective_date_transaction": "03/01/2026",
"effective_date_transaction_al": "03/01/2026",
"effective_date_transaction_wc": "03/01/2026",
"cancellation_reason": ["non_payment"],
"internal_cancellation_reason": ["<string>"],
"cancellation_back_date_reason": "<string>",
"cancellation_back_date_reason_other": "<string>"
}
headers = {
"AccessToken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {AccessToken: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
effective_date_transaction: '03/01/2026',
effective_date_transaction_al: '03/01/2026',
effective_date_transaction_wc: '03/01/2026',
cancellation_reason: ['non_payment'],
internal_cancellation_reason: ['<string>'],
cancellation_back_date_reason: '<string>',
cancellation_back_date_reason_other: '<string>'
})
};
fetch('https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'effective_date_transaction' => '03/01/2026',
'effective_date_transaction_al' => '03/01/2026',
'effective_date_transaction_wc' => '03/01/2026',
'cancellation_reason' => [
'non_payment'
],
'internal_cancellation_reason' => [
'<string>'
],
'cancellation_back_date_reason' => '<string>',
'cancellation_back_date_reason_other' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"AccessToken: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request"
payload := strings.NewReader("{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("AccessToken", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request")
.header("AccessToken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["AccessToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"submission_number": "<string>",
"transaction_id": 123,
"cancellation_status": "<string>",
"transportation_submission_id": 123,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"cancellation_notice": {
"phase": "request",
"state": "<string>",
"reason": "<string>",
"notice_minimum_required": true,
"ground": "non_payment",
"floor_days": 123,
"days_in_force": 123,
"minimum_date": "2023-12-25",
"held": true,
"hold_reason": "<string>",
"changes": {},
"date_measurements": {},
"current_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"enabled": true,
"historical_exempt": true,
"evaluated_at": "2023-11-07T05:31:56Z",
"stored_reason": "<string>",
"approved_reason": "<string>",
"historical_actor_id": 123,
"historical_source": "<string>",
"historical_justification": "<string>",
"preview_stale": true,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"date_role": "proposal",
"wc_action": "cancel",
"persisted_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"request_decision": {
"changes": {},
"notice_minimum_required": true
}
}
}{
"error": "<string>",
"errors": {},
"reason_code": "cancellation_notice_manual_review",
"cancellation_notice": {
"phase": "request",
"state": "<string>",
"reason": "<string>",
"notice_minimum_required": true,
"ground": "non_payment",
"floor_days": 123,
"days_in_force": 123,
"minimum_date": "2023-12-25",
"held": true,
"hold_reason": "<string>",
"changes": {},
"date_measurements": {},
"current_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"enabled": true,
"historical_exempt": true,
"evaluated_at": "2023-11-07T05:31:56Z",
"stored_reason": "<string>",
"approved_reason": "<string>",
"historical_actor_id": 123,
"historical_source": "<string>",
"historical_justification": "<string>",
"preview_stale": true,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"date_role": "proposal",
"wc_action": "cancel",
"persisted_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"request_decision": {
"changes": {},
"notice_minimum_required": true
}
}
}Policy Lifecycle
Request Cancellation
Creates a cancellation endorsement. Optional reason arrays become approval defaults when reason-aware request intake is enabled. Request enforcement uses the state-and-reason minimum from the request day and can lengthen dates; approval may lengthen them again. Responses retain existing fields and add actual stored ISO dates plus recorded or advisory notice-rule metadata. See the Policy Lifecycle guide for separately controlled, default-off rollout behavior. Pure whole-policy insured_broker_request cancellations have no statutory notice minimum (notice_minimum_required=false, floor_days and minimum_date null), but still validate applicable dates within the term. Legacy courtesy/carrier PDFs, emails and filing work can still occur. Mixed/unknown reasons remain conservative; partial NOC generation always applies the minimum.
POST
/
submission
/
{displayId}
/
cancel-request
Request Cancellation
curl --request POST \
--url https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request \
--header 'AccessToken: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"effective_date_transaction": "03/01/2026",
"effective_date_transaction_al": "03/01/2026",
"effective_date_transaction_wc": "03/01/2026",
"cancellation_reason": [
"non_payment"
],
"internal_cancellation_reason": [
"<string>"
],
"cancellation_back_date_reason": "<string>",
"cancellation_back_date_reason_other": "<string>"
}
'import requests
url = "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request"
payload = {
"effective_date_transaction": "03/01/2026",
"effective_date_transaction_al": "03/01/2026",
"effective_date_transaction_wc": "03/01/2026",
"cancellation_reason": ["non_payment"],
"internal_cancellation_reason": ["<string>"],
"cancellation_back_date_reason": "<string>",
"cancellation_back_date_reason_other": "<string>"
}
headers = {
"AccessToken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {AccessToken: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
effective_date_transaction: '03/01/2026',
effective_date_transaction_al: '03/01/2026',
effective_date_transaction_wc: '03/01/2026',
cancellation_reason: ['non_payment'],
internal_cancellation_reason: ['<string>'],
cancellation_back_date_reason: '<string>',
cancellation_back_date_reason_other: '<string>'
})
};
fetch('https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'effective_date_transaction' => '03/01/2026',
'effective_date_transaction_al' => '03/01/2026',
'effective_date_transaction_wc' => '03/01/2026',
'cancellation_reason' => [
'non_payment'
],
'internal_cancellation_reason' => [
'<string>'
],
'cancellation_back_date_reason' => '<string>',
'cancellation_back_date_reason_other' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"AccessToken: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request"
payload := strings.NewReader("{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("AccessToken", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request")
.header("AccessToken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coverwhale.dev/v1/submission/{displayId}/cancel-request")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["AccessToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"effective_date_transaction\": \"03/01/2026\",\n \"effective_date_transaction_al\": \"03/01/2026\",\n \"effective_date_transaction_wc\": \"03/01/2026\",\n \"cancellation_reason\": [\n \"non_payment\"\n ],\n \"internal_cancellation_reason\": [\n \"<string>\"\n ],\n \"cancellation_back_date_reason\": \"<string>\",\n \"cancellation_back_date_reason_other\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"submission_number": "<string>",
"transaction_id": 123,
"cancellation_status": "<string>",
"transportation_submission_id": 123,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"cancellation_notice": {
"phase": "request",
"state": "<string>",
"reason": "<string>",
"notice_minimum_required": true,
"ground": "non_payment",
"floor_days": 123,
"days_in_force": 123,
"minimum_date": "2023-12-25",
"held": true,
"hold_reason": "<string>",
"changes": {},
"date_measurements": {},
"current_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"enabled": true,
"historical_exempt": true,
"evaluated_at": "2023-11-07T05:31:56Z",
"stored_reason": "<string>",
"approved_reason": "<string>",
"historical_actor_id": 123,
"historical_source": "<string>",
"historical_justification": "<string>",
"preview_stale": true,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"date_role": "proposal",
"wc_action": "cancel",
"persisted_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"request_decision": {
"changes": {},
"notice_minimum_required": true
}
}
}{
"error": "<string>",
"errors": {},
"reason_code": "cancellation_notice_manual_review",
"cancellation_notice": {
"phase": "request",
"state": "<string>",
"reason": "<string>",
"notice_minimum_required": true,
"ground": "non_payment",
"floor_days": 123,
"days_in_force": 123,
"minimum_date": "2023-12-25",
"held": true,
"hold_reason": "<string>",
"changes": {},
"date_measurements": {},
"current_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"enabled": true,
"historical_exempt": true,
"evaluated_at": "2023-11-07T05:31:56Z",
"stored_reason": "<string>",
"approved_reason": "<string>",
"historical_actor_id": 123,
"historical_source": "<string>",
"historical_justification": "<string>",
"preview_stale": true,
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25",
"date_role": "proposal",
"wc_action": "cancel",
"persisted_dates": {
"effective_date_transaction": "2023-12-25",
"effective_date_transaction_al": "2023-12-25",
"effective_date_transaction_wc": "2023-12-25"
},
"request_decision": {
"changes": {},
"notice_minimum_required": true
}
}
}Create a cancellation endorsement, then approve that exact transaction with
Approve Cancellation.
Keep
transportation_submission_id, the immutable endorsement ID returned by
the request, alongside transaction_id.
Dates and reason defaults
Send request dates asMM/DD/YYYY. effective_date_transaction is required;
separate AL and Workers’ Comp dates are optional. Supplied dates must be within
the policy term. When request-reason intake is enabled, supplied
cancellation_reason and internal_cancellation_reason must be valid nonempty
reason-code arrays. When intake is disabled, these fields retain the legacy
behavior: they are ignored, including scalar, empty-array, and unknown-key
extras. Enabling approval enforcement alone does not enable request intake.
When reason-aware request intake is enabled, the external reason chooses the
state notice rule from the request day. Non-payment reasons use the non-payment
rule; other cancellation reasons that require the statutory minimum use the underwriting rule. The minimum can
lengthen an earlier date and preserves a later requested date. Applicable WC
dates are also checked when the reason cancels WC.
A whole-policy cancellation whose reasons contain only insured_broker_request
has no statutory notice minimum. Legacy courtesy/carrier documents, emails,
and filing work can still occur. Its metadata reports
notice_minimum_required: false, floor_days: null, and minimum_date: null.
Applicable dates must still be present and within the policy term. Mixed or
unknown reason sets use the conservative notice rule. Partial cancellations
that generate a NOC still apply the minimum, including insured-requested partial
cancellations.
The supplied reasons become approval defaults only when request intake is
enabled. Approval can supply a different external reason, which wins and is
re-evaluated from the approval day when approval enforcement is enabled.
Continue supplying the final reason at approval for compatibility across
rollout configurations. See cancellation rollout and final dates.
An authorized historical correction can supply cancellation_back_date_reason.
For Other, also supply nonblank string cancellation_back_date_reason_other.
PAS stores Other - <trimmed details> and validates the complete justification
at no more than 255 UTF-8 characters before creating the endorsement. Exactly
255 characters is valid; invalid or longer proof returns field-validation 422
without creating a cancellation. The recorded historical justification matches
the saved text. These fields grant no backdating authority; existing permissions
and valid policy-term dates still apply.
Stored response dates
The response adds ISOYYYY-MM-DD fields for the dates actually stored by PAS:
effective_date_transaction, effective_date_transaction_al, and
effective_date_transaction_wc. A null value can reflect a line outside this
cancellation or an unavailable stored date. Use coverage context and the
decision’s wc_action to determine whether WC is canceled, retained, or not
applicable.
Keep the original request as provenance and read the dates again after approval.
cancellation_notice describes a recorded rule evaluation or an advisory
proposal. Its phase, date_role, and enabled apply to that evaluation. Its
proposed dates and minimum_date can differ from the top-level stored dates, especially while
enforcement is disabled. Use the stored dates for notices and lifecycle clocks,
and PAS’s final premium values after approval.
Manual review
With enforcement enabled, an unresolved rule, missing applicable date, incomplete term, or notice minimum after policy expiration returns HTTP422 with
reason_code: cancellation_notice_manual_review. The response’s error and
cancellation_notice.hold_reason explain the hold. Review it with Cover Whale;
the API does not clamp the notice minimum to expiration. A validation failure
can also return 422 with field-level errors.Authorizations
JWT returned as AccessToken by the /authentication endpoint (the Cognito ID token carrying the email claim). It expires after 3600 seconds.
Headers
Path Parameters
Submission display ID
Body
application/json
Requested general cancellation date (MM/DD/YYYY), within the policy term. Read actual stored dates from the response and again after approval.
Example:
"03/01/2026"
Optional separate requested AL cancellation date (MM/DD/YYYY), within the policy term. A missing applicable date can require manual review under enforcement.
Example:
"03/01/2026"
Optional separate requested Workers' Comp cancellation date (MM/DD/YYYY), within the policy term. Applicable WC dates are checked when the reason cancels WC.
Example:
"03/01/2026"
Optional valid external reason codes. Reason-aware request intake retains these as approval defaults and uses them to choose the notice rule. An explicit approval reason overrides the stored default.
Minimum array length:
1Example:
["non_payment"]
Optional valid internal reason codes, retained on the request when reason-aware intake is enabled.
Minimum array length:
1Historical correction justification for an authorized actor. Other requires cancellation_back_date_reason_other. PAS validates the complete normalized justification at no more than 255 UTF-8 characters before creating the endorsement; these fields grant no backdating authority.
Required nonblank string details when cancellation_back_date_reason is Other. The stored value is Other - ; its complete normalized length must be at most 255 UTF-8 characters. The historical decision receipt retains the same full text.
Response
Cancellation request created
Example:
"success"
Immutable cancellation endorsement row ID. Keep it alongside transaction_id, which can be reused.
Actual persisted general cancellation date (YYYY-MM-DD). Use final approval dates for notices and lifecycle clocks.
Actual persisted AL cancellation date (YYYY-MM-DD), or null if no stored date is available. Determine applicability from coverage context.
Actual persisted WC cancellation date (YYYY-MM-DD) when wc_action is cancel; otherwise null. Determine applicability from coverage context and the decision.
Persisted notice-rule decision or request history; otherwise an advisory preview. Properties vary by phase and hold. Actual persisted dates are the top-level response fields.
Show child attributes
Show child attributes