Quickstart

This guide walks you through authenticating with the API and getting your first insurance quote.

Prerequisites

API credentials (username and password) from Cover Whale — request access if you don’t have them
A tool for making HTTP requests (cURL, Postman, or your preferred HTTP client)

Step 1: Authenticate

Exchange your credentials for an access token:

curl -X POST https://api.coverwhale.dev/v1/authentication \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "AccessToken": "eyJraWQiOiJnRk5oTTh2RnRKWXVDVXU1S...",
  "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOi...",
  "ExpiresIn": 3600
}

Save the AccessToken — you’ll include it in all subsequent requests. It expires after 3600 seconds (1 hour).

Step 2: Get an Indication

Submit basic information to get preliminary pricing. The request body is organized by section — insured info, coverage options, and addresses:

curl -X POST https://api.coverwhale.dev/v1/indication \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -d '{
    "insuredInformation": {
      "dotNumber": 1234567,
      "legalName": "ACME TRUCKING LLC",
      "yearsInBusiness": 3
    },
    "coverage": {
      "requestAl": "Y",
      "requestApd": "Y",
      "requestMtc": "Y",
      "effectiveDate": "03/01/2026"
    },
    "garageAddress": {
      "garageState": "CA",
      "garageZip": "90016"
    },
    "mailingAddress": {
      "mailingState": "CA",
      "mailingZip": "90016"
    },
    "limits": {
      "nbrOfTrucks": 3,
      "valueOfTrucks": 150000
    }
  }'

Response:

{
  "status": "Indication",
  "submission_number": "2172961",
  "coverages": {
    "al": {
      "totalCost": 0,
      "premium": 20617.52,
      "limit": 1000000,
      "deductible": 0
    }
  }
}

The response includes preliminary pricing for each requested coverage line (AL, APD, MTC, etc.).

The submission_number in the response is your key identifier. Save it — you’ll use it for checking status, binding, endorsements, and every other operation on this submission.

Step 3: Get a Full Quote

For final pricing, submit the complete application with insured details, addresses, vehicles, and drivers:

curl -X POST https://api.coverwhale.dev/v1/quote \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -d '{
    "insuredInformation": {
      "dotNumber": 1234567,
      "legalName": "ACME TRUCKING LLC",
      "yearsInBusiness": 3,
      "email": "insured@example.com"
    },
    "coverage": {
      "requestAl": "Y",
      "requestApd": "Y",
      "requestMtc": "Y",
      "brokerFeeAL": 10,
      "brokerFeeAPD": 10,
      "brokerFeeMTC": 10,
      "effectiveDate": "03/01/2026"
    },
    "garageAddress": {
      "garageStreet": "123 Main St",
      "garageCity": "Los Angeles",
      "garageState": "CA",
      "garageZip": "90016",
      "garageCounty": "Los Angeles"
    },
    "mailingAddress": {
      "mailingStreet": "123 Main St",
      "mailingCity": "Los Angeles",
      "mailingState": "CA",
      "mailingZip": "90016",
      "mailingCounty": "Los Angeles"
    },
    "limits": {
      "nbrOfTrucks": 3,
      "valueOfTrucks": 150000,
      "limitAutoLiability": 1000000
    },
    "vehicles": [
      {
        "year": 2020,
        "make": "Freightliner",
        "model": "Cascadia",
        "vin": "1FUJGLDR0CLBK5432",
        "value": 55000,
        "classKey": "1"
      }
    ],
    "drivers": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "06/15/1985",
        "licenseState": "CA",
        "licenseNumber": "D1234567",
        "yearsExperience": 8
      }
    ]
  }'

Response:

{
  "status": "Quoted",
  "submission_number": "2172961",
  "coverages": {
    "al": {
      "totalCost": 20617.52,
      "premium": 20617.52,
      "limit": 1000000,
      "deductible": 0
    }
  }
}

The response includes final pricing with premiums, fees, limits, and deductibles for each coverage line.

Step 4: Check Submission Status

After submitting a quote, check its status. The submission moves through a lifecycle: Submitted → In Review → Quoted → Request to Bind → Bound.

curl -X GET https://api.coverwhale.dev/v1/submission/2172961 \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_ACCESS_TOKEN"

Once the status is Quoted, you can proceed to bind.

Step 5: Bind the Quote

Binding converts the quote into an active insurance policy. You’ll select which coverage lines to include and provide binding details. Broker service fees are not submitted at bind — they were captured on the quote and are automatically carried forward for the coverage lines you include here.

curl -X PUT https://api.coverwhale.dev/v1/bind/2172961 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: YOUR_ACCESS_TOKEN" \
  -d '{
    "coverage": {
      "includeAL": "Y",
      "includeAPD": "Y",
      "includeMTC": "Y",
      "optInCWFinancing": "N",
      "electTRIA": "N",
      "effectiveDate": "03/01/2026"
    },
    "bindingMethod": {
      "signFirst": "N",
      "electronicSignature": "Y",
      "retailAgentEmail": "agent@example.com",
      "insuredEmail": "insured@example.com",
      "insuredFullName": "John Doe"
    },
    "shippingAddress": {
      "dashcam_shipping_address": "insured",
      "street": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90016",
      "county": "Los Angeles"
    }
  }'

Response:

{
  "status": "success"
}

After binding, the submission status changes to Request to Bind. Cover Whale’s underwriting team reviews and finalizes the policy — the status then moves to Bound and policy documents are generated. That’s the complete flow: Authenticate → Get Pricing → Submit Quote → Bind Policy.

Next Steps

Integration Checklist

Data you’ll need to collect from the insured

Quoting Guide

Indication vs. full quote, coverage types, and decline reasons

Policy Lifecycle

Endorsements, cancellations, and post-bind operations

API Reference

Full endpoint documentation with request/response schemas

Getting Started

Guides

Webhooks

Quickstart

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: Get an Indication

Step 3: Get a Full Quote

Step 4: Check Submission Status

Step 5: Bind the Quote

Next Steps

Integration Checklist

Quoting Guide

Policy Lifecycle

API Reference

​Quickstart

​Prerequisites

​Step 1: Authenticate

​Step 2: Get an Indication

​Step 3: Get a Full Quote

​Step 4: Check Submission Status

​Step 5: Bind the Quote

​Next Steps

Integration Checklist

Quoting Guide

Policy Lifecycle

API Reference

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: Get an Indication

Step 3: Get a Full Quote

Step 4: Check Submission Status

Step 5: Bind the Quote

Next Steps