Skip to main content

​
Policy Lifecycle

Once a submission is quoted, you can bind it through the API to create an active policy. This guide covers the binding process and what happens after.

​
Binding a Quote

To bind a quoted submission, submit a PUT request to /bind/{displayId} with coverage selections, binding method, and shipping details.

​
Prerequisites

  • The submission must be in Quoted status
  • You must select which coverage lines to include
  • An effective date must be provided

​
Bind Request

A successful bind request returns:
The submission status then moves to Request to Bind while underwriting finalizes the policy.

​
Coverage Selection

At bind time, you choose which coverage lines to include. Set each to "Y" to include or omit to exclude:

​
Broker Fees

Broker service fees are captured on the quote (or indication) request, not on bind. Submit them under coverage on POST /v1/quote:
  • brokerFeeAL, brokerFeeAPD, brokerFeeMTC, brokerFeeTGL, brokerFeeNTL
Each is a number between 0 and 1,000 (USD, per coverage line). When you bind, the fees you provided at quote are automatically carried forward for whichever coverage lines you include*. Any coverage line you omit at bind has its broker fee zeroed out for the resulting policy.

​
Financing

Set optInCWFinancing to "Y" to use Cover Whale’s premium financing option. When opted in, the payment type is automatically set to Cover Whale financing.

​
TRIA Coverage

Set electTRIA to "Y" to elect Terrorism Risk Insurance Act coverage, or "N" to decline.

​
Electronic Signature

The bindingMethod object controls how the policy documents are signed:

​
Dashcam Shipping

Cover Whale may ship dashcams as part of the policy. The shippingAddress object specifies where to send them:
  • Set dashcam_shipping_address to "insured" to ship to the insured’s address on file
  • Provide street, city, state, zip, and county for a custom shipping address

​
What Happens After Binding

Once a bind request is successfully submitted:
  1. The submission status changes to Request to Bind
  2. Cover Whale’s underwriting team reviews and approves the bind
  3. Policy numbers are assigned for each coverage line
  4. Policy documents are generated
  5. The submission status changes to Bound
  6. The agent and insured receive confirmation emails

​
Error Handling

The bind endpoint returns 404 if:
  • The submission is not in Quoted status
  • Required fields are missing or invalid
  • The submission cannot be found

​
Post-Bind Operations

After a policy is bound, additional lifecycle operations are available: See the Policy Lifecycle section in the API Reference for full endpoint documentation.

​
Cancellation Dates and Rollout

Cancellation has separate request and approval steps. Send requested dates as MM/DD/YYYY; successful responses return the actual stored dates as ISO YYYY-MM-DD. Retain the original request and the immutable transportation_submission_id, then consume the final approval dates for notices and lifecycle clocks. Approval can move the dates again. Read final premium values from Submission Details after approval; do not recalculate them from the requested dates. Two separately controlled features default off: Observe-only telemetry can run before enforcement. The controls are managed by Cover Whale; sending a reason does not enable either one. Send an explicit external reason at approval to work across rollout states. An omitted external reason may use the stored request reason only when either request intake or approval notice enforcement is enabled. An explicit approval reason wins over that default. With both controls disabled, the existing request-stage underwriting backstop remains under its existing control. It is not enabled or disabled by a reason field in the API body. For new cancellations requiring a statutory minimum, the enabled rule lengthens an earlier date to the minimum and preserves a later date. It covers applicable general, AL, and canceled WC dates. Approved historical corrections with attributable authorization retain their dates; this is not an API opt-out from notice rules. If the minimum exceeds expiration, enforcement holds the operation for manual review instead of shortening notice to fit the term. Partial-coverage changes evaluate the lines actually being canceled. Whole-policy cancellations whose parsed reasons contain only insured_broker_request have no statutory notice minimum. Legacy courtesy/carrier documents, emails, and filing work can still occur. Their metadata has 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 remain conservative. Partial NOC generation always applies the minimum, including insured-requested partial cancellations. Partial selection accepts supported lines selected with true, 1, "1", or "true"; false values do not select a line. Invalid values, unknown keys, empty/all-false selections, and separate WC cancellations are rejected. Unselected coverage dates retain their stored values. The additive cancellation_notice object records the decision when applied or retains request history; without a recorded decision, it is an advisory preview. Read phase, date_role, enabled, notice_minimum_required, historical_exempt, held, minimum_date, changes, and date_measurements in that context. date_role distinguishes a proposal from an applied evaluation or a persisted record. A recorded approval may retain the earlier request_decision, and persisted_dates captures the stored values with the decision. Use top-level response dates for the current actual values. changes is a map keyed by date field when dates change, or an empty array ([]) when none are adjusted, including historical exemptions. The same shape applies inside request_decision. An advisory held value on a successful legacy response does not mean the operation was blocked. Proposed dates inside this object are not the top-level actual stored dates. AL or WC may have a null date when no date is available or the line is outside this cancellation. wc_action identifies WC as cancel, retain, or not_applicable. Determine applicability from coverage context, and reconcile a missing applicable date; do not infer that coverage is absent or present a requested date as confirmed. HTTP 422 with reason_code: cancellation_notice_manual_review is an actual hold. Its error and cancellation_notice.hold_reason explain the review needed. An intent-backed notice handoff may need review after approval commits. cancel-approve then returns HTTP 500 with approval_saved: true, reason_code: cancellation_notice_continuation_review, actual saved dates and notice_continuation (id, phase, and specific reason_code). A generic error-only 500 does not establish committed approval. Preserve the receipt and reconcile with Cover Whale; never blindly repeat a saved approval or uncertain filing/queue handoff. cancel returns 409 with the same receipt shape when notice readiness blocks finalization. A precommit 422 notice hold remains a refusal before approval. Finalization also requires a confirmed queue handoff for any required physical-print chain; PDF readiness alone is insufficient. A zero physical-job handoff completes after actual PDF generation without claiming print delivery. Readiness and initial queue acceptance remain separate from provider delivery and do not establish exactly-once delivery. See Request Cancellation and Approve Cancellation for the request schemas and response fields.