Skip to main content

​
Integration Patterns

Answers to the questions developers ask most when building against the Cover Whale API.

​
Should I start with an indication or a full quote?

It depends on your workflow:
Use an Indication when…Use a Full Quote when…
You want to quickly screen whether a prospect is eligibleYou have all the insured’s information ready
You’re building a “get a quick estimate” featureYou’re building a full application flow
You don’t have vehicle/driver details yetYou want binding-eligible pricing
Common pattern: Show an indication first as a preview, then collect remaining details and submit a full quote when the user is ready to proceed.

​
What’s the typical integration flow?

Most integrations follow this sequence: 
1. Authenticate          → Get an AccessToken
2. Get Indication        → Quick pricing check (optional)
3. Get Full Quote        → Binding-eligible pricing
4. Check Status          → Confirm submission is "Quoted"
5. Bind                  → Convert quote to active policy
6. Monitor Status        → Confirm submission moves to "Bound"
Steps 2-3 can happen in one call if you have all the data upfront. The indication step is optional but useful for pre-screening.

​
How should I poll for status changes?

After submitting a quote or bind request, the submission goes through underwriting review. There are no webhooks — you’ll need to poll. Recommended approach:
  • Poll GET /submission/{displayId} every 30-60 seconds
  • Stop polling once the status reaches a terminal state (Quoted, Bound, or Declined)
  • Implement a maximum polling duration (e.g., 5 minutes for quoting, 24 hours for binding)
# Example: poll until status changes from "Submitted"
while true; do
  STATUS=$(curl -s https://app.coverwhale.com/api/v1/submission/2172961 \
    -H "AccessToken: YOUR_TOKEN" | jq -r '.status')

  echo "Current status: $STATUS"

  if [ "$STATUS" != "Submitted" ]; then
    break
  fi

  sleep 30
done

​
Can I modify a submission after quoting?

Yes. Use the Submission Data endpoints to update fields, add/remove vehicles, drivers, and trailers. After modifications, call POST .../recalculate-rates to get updated pricing. The submission must be in a modifiable status — you cannot modify a submission that’s already bound.

​
What happens if a quote expires?

Quotes have a validity window set by underwriting. If the effective date passes or the quote ages out, you’ll need to resubmit. The API will return an error if you try to bind an expired quote.

​
Can I submit multiple quotes at once?

Yes. Each POST /getquote call creates an independent submission with its own submission_number. You can submit as many concurrent quotes as needed — just track each submission number separately.

​
How do I handle token expiration?

Tokens expire after 1 hour. Two approaches: Proactive (recommended): Track when the token was issued, and refresh it before expiration: 
import time

token_issued_at = time.time()
TOKEN_LIFETIME = 3600  # 1 hour

def get_token():
    global token_issued_at, access_token
    if time.time() - token_issued_at > (TOKEN_LIFETIME - 300):  # refresh 5 min early
        access_token = refresh_token()
        token_issued_at = time.time()
    return access_token
Reactive: Catch 401 responses and refresh on failure: 
response = make_api_call(access_token)
if response.status_code == 401:
    access_token = refresh_token()
    response = make_api_call(access_token)  # retry

​
What data format should I expect?

  • Dates are always MM/DD/YYYY (e.g., 03/01/2026)
  • Currency values are numbers without currency symbols (e.g., 20617.52)
  • Boolean-like fields use "Y" / "N" strings, not true / false
  • State codes are 2-letter abbreviations (e.g., "CA", "TX")

​
What if a submission is declined?

The response from the quote endpoint will include the decline reason. Common causes:
  • DOT number not found or inactive with FMCSA
  • Insufficient business tenure (typically need 1+ years)
  • Operating in a restricted state
  • Adverse loss history
  • Fleet size outside underwriting guidelines
Declines are final for that submission. If the underlying issue is resolved (e.g., the insured gets more experience), you can submit a new quote.