Skip to main content

​
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://app.coverwhale.com/api/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://app.coverwhale.com/api/v1/getindication \
  -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://app.coverwhale.com/api/v1/getquote \
  -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",
      "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://app.coverwhale.com/api/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: 
curl -X PUT https://app.coverwhale.com/api/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",
      "brokerFeeAL": 10,
      "brokerFeeAPD": 10,
      "brokerFeeMTC": 10,
      "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