Endorsements

An endorsement modifies an active (bound) policy — adding vehicles, removing drivers, changing limits, or updating other details mid-term. The API handles endorsements as a new transaction on the same submission, following a lifecycle similar to new business.

How Endorsements Work

When you create an endorsement, the API duplicates the current policy into a new transaction record. You then modify that transaction (add/remove vehicles, update details), quote the changes, and bind. The original policy remains untouched until the endorsement is bound.

Create Endorsement    → Duplicates bound policy into new transaction
Make Changes          → Add/remove vehicles, drivers, trailers, update fields
Quote Endorsement     → Recalculate rates with the changes
Bind                  → Apply the endorsement to the active policy

Each endorsement gets its own transaction_id (2, 3, 4, …) while sharing the same submission_number as the original policy. The original new-business transaction is always transaction_id 1.

Step 1: Create the Endorsement

Start by creating an endorsement on a bound submission. You only need the endorsement effective date:

curl -X POST https://api.coverwhale.dev/v1/submission/2172961/1/endorsement \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "effective_date_transaction": "06/15/2026"
  }'

Parameter	Description
`2172961` (path)	The submission’s display ID
`1` (path)	The transaction ID of the bound policy
`effective_date_transaction`	When the endorsement takes effect (MM/DD/YYYY)

Response:

{
  "status": "success",
  "submission_number": "2172961",
  "transaction_id": 2,
  "endorsement_status": "Submitted"
}

The new transaction_id (here 2) is what you’ll use for all subsequent calls. The endorsement starts in Submitted status with a full copy of the current policy data.

The submission must be in Bound status. You cannot create an endorsement on a submission that is still being quoted or is pending bind.

Step 2: Make Changes

With the endorsement created, use the Submission Data endpoints to make your changes. All modification endpoints take both displayId and transactionId — use the new transaction ID from Step 1.

Add a Vehicle

curl -X POST https://api.coverwhale.dev/v1/submission/2172961/2/vehicle \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "vehicle_id_number": "3AKJHHDR5LSLN0422",
    "year": 2022,
    "make": "Freightliner",
    "model": "Cascadia",
    "class": "1",
    "value": 85000
  }'

Update an Existing Vehicle

curl -X PUT https://api.coverwhale.dev/v1/submission/2172961/2/vehicle/456 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "value": 60000
  }'

Only send the fields that changed — unchanged fields are preserved.

Remove a Vehicle

curl -X DELETE https://api.coverwhale.dev/v1/submission/2172961/2/vehicle/789 \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN"

Other Modifications

The same pattern applies to drivers, trailers, and submission-level fields:

Change	Endpoint	Method
Add driver	`/submission/{displayId}/{transactionId}/driver`	`POST`
Update driver	`/submission/{displayId}/{transactionId}/driver/{driverId}`	`PUT`
Remove driver	`/submission/{displayId}/{transactionId}/driver/{driverId}`	`DELETE`
Add trailer	`/submission/{displayId}/{transactionId}/trailer`	`POST`
Remove trailer	`/submission/{displayId}/{transactionId}/trailer/{trailerId}`	`DELETE`
Update insured/address/limits	`/submission/{displayId}/{transactionId}`	`PUT`

You can make multiple changes before quoting. Add two vehicles, remove a driver, and update the radius — then quote everything at once in Step 3.

Step 3: Quote the Endorsement

After making all your changes, request updated pricing:

curl -X POST https://api.coverwhale.dev/v1/submission/2172961/2/quote-endorsement \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN"

No request body is needed — the endpoint recalculates rates based on the current state of the endorsement transaction. Response:

{
  "status": "success",
  "submission_number": "2172961",
  "transaction_id": 2,
  "endorsement_status": "Quoted",
  "rates": {
    "al": {
      "total_premium": 24750.00,
      "total_premium_fees_taxes": 26100.50
    },
    "apd": {
      "total_premium": 5100.00,
      "total_premium_fees_taxes": 5400.25
    }
  }
}

The rates object shows the new premium for each coverage line, reflecting your changes.

If you make additional changes after quoting (e.g., add another vehicle), the endorsement status resets to Submitted and you must call quote-endorsement again before binding.

Step 4: Bind the Endorsement

Once the endorsement is quoted, bind it using the same bind endpoint as new business:

curl -X PUT https://api.coverwhale.dev/v1/bind/2172961 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "bindingMethod": {
      "retailAgentEmail": "agent@example.com",
      "insuredEmail": "insured@example.com",
      "insuredFullName": "John Doe"
    }
  }'

The bind request for endorsements is simpler than new business:

Field	Required	Notes
`bindingMethod.retailAgentEmail`	Yes	Agent’s email for confirmation
`bindingMethod.insuredEmail`	Yes	Insured’s email for signature
`bindingMethod.insuredFullName`	Yes	Insured’s full name
`coverage`	No	Coverage selections and TRIA are inherited from the original policy
`shippingAddress`	No	Not required for endorsements

Response:

{
  "status": "success"
}

After binding, the endorsement moves to Request to Bind, then to Bound once underwriting approves.

Complete Example

Here’s the full endorsement flow — adding a new truck to an existing policy:

# 1. Create endorsement on bound policy (transaction 1)
curl -X POST https://api.coverwhale.dev/v1/submission/2172961/1/endorsement \
  -H "Content-Type: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{"effective_date_transaction": "06/15/2026"}'
# Response: {"transaction_id": 2, "endorsement_status": "Submitted"}

# 2. Add the new vehicle to endorsement (transaction 2)
curl -X POST https://api.coverwhale.dev/v1/submission/2172961/2/vehicle \
  -H "Content-Type: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "vehicle_id_number": "3AKJHHDR5LSLN0422",
    "year": 2022,
    "make": "Freightliner",
    "model": "Cascadia",
    "class": "1",
    "value": 85000
  }'

# 3. Quote the endorsement
curl -X POST https://api.coverwhale.dev/v1/submission/2172961/2/quote-endorsement \
  -H "AccessToken: YOUR_TOKEN"
# Response: {"endorsement_status": "Quoted", "rates": {...}}

# 4. Bind the endorsement
curl -X PUT https://api.coverwhale.dev/v1/bind/2172961 \
  -H "Content-Type: application/json" \
  -H "AccessToken: YOUR_TOKEN" \
  -d '{
    "bindingMethod": {
      "retailAgentEmail": "agent@example.com",
      "insuredEmail": "insured@example.com",
      "insuredFullName": "John Doe"
    }
  }'
# Response: {"status": "success"}

Endorsement Status Flow

Submitted → Quoted → Request to Bind → Bound
    ↑__________|
    (if modified after quoting, resets to Submitted)

Common Endorsement Scenarios

Scenario	What to Do
Add a new truck to the fleet	Create endorsement, add vehicle, quote, bind
Replace a totaled vehicle	Create endorsement, remove old vehicle, add new vehicle, quote, bind
Add a new driver	Create endorsement, add driver, quote, bind
Change liability limits	Create endorsement, update submission limits, quote, bind
Update garage address	Create endorsement, update submission address, quote, bind

Create Endorsement — Create endorsement endpoint schema
Quote Endorsement — Quote endorsement endpoint schema
Bind a Quoted Submission — Bind endpoint schema
Update Submission — Update submission fields
Add Vehicle — Add vehicle endpoint schema
Policy Lifecycle — Binding and post-bind operations overview

Getting Started

Guides

Webhooks

Endorsements

Endorsements

How Endorsements Work

Step 1: Create the Endorsement

Step 2: Make Changes

Add a Vehicle

Update an Existing Vehicle

Remove a Vehicle

Other Modifications

Step 3: Quote the Endorsement

Step 4: Bind the Endorsement

Complete Example

Endorsement Status Flow

Common Endorsement Scenarios

​Endorsements

​How Endorsements Work

​Step 1: Create the Endorsement

​Step 2: Make Changes

​Add a Vehicle

​Update an Existing Vehicle

​Remove a Vehicle

​Other Modifications

​Step 3: Quote the Endorsement

​Step 4: Bind the Endorsement

​Complete Example

​Endorsement Status Flow

​Common Endorsement Scenarios

​Related Endpoints

Endorsements

How Endorsements Work

Step 1: Create the Endorsement

Step 2: Make Changes

Add a Vehicle

Update an Existing Vehicle

Remove a Vehicle

Other Modifications

Step 3: Quote the Endorsement

Step 4: Bind the Endorsement

Complete Example

Endorsement Status Flow

Common Endorsement Scenarios

Related Endpoints