> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coverwhale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Endorsements

> How to modify a bound policy through the endorsement workflow

# 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.

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

<Info>
  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.
</Info>

## Step 1: Create the Endorsement

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

```bash theme={null}
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:

```json theme={null}
{
  "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.

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

## 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`    |

<Tip>
  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.
</Tip>

## Step 3: Quote the Endorsement

After making all your changes, request updated pricing:

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## Step 4: Bind the Endorsement

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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           |

## Related Endpoints

* [Create Endorsement](/api-reference/policy-lifecycle/create-endorsement) — Create endorsement endpoint schema
* [Quote Endorsement](/api-reference/submission-data/quote-endorsement) — Quote endorsement endpoint schema
* [Bind a Quoted Submission](/api-reference/binding/bind-a-quoted-submission) — Bind endpoint schema
* [Update Submission](/api-reference/submission-data/update-submission) — Update submission fields
* [Add Vehicle](/api-reference/submission-data/add-vehicle) — Add vehicle endpoint schema
* [Policy Lifecycle](/guides/policy-lifecycle) — Binding and post-bind operations overview