Getting Started

This walkthrough takes you from nothing to a working integration: authenticate, make your first call, and set up a webhook so Cover Whale pushes you updates instead of you polling. Everything here runs against the sandbox (api.coverwhale.dev), so nothing you do creates a real policy or premium.

Every endpoint in the API Reference has an interactive “Try it” console — the fastest way to experiment while you read. Prefer Postman? Jump to Tooling for a one-click collection.

Before you start

Sandbox credentials — a username and password for api.coverwhale.dev. Request them from api-support@coverwhale.com. Sandbox and production use separate credentials.
A REST client — cURL, Postman, or your language’s HTTP library.
(For webhooks) an HTTPS endpoint you control that can receive a POST. A request-bin style tool is fine for a first test.

Step 1 — Authenticate

Exchange your credentials for an access token. It’s good for one hour.

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"
  }'

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

Save the AccessToken — you’ll send it in the AccessToken header on every other request. When it expires, refresh it (see Authentication) instead of re-sending your password.

Step 2 — Make your first call

Look up a submission’s current status. Substitute a displayId from your account.

curl https://api.coverwhale.dev/v1/submission/2261310 \
  -H "Accept: application/json" \
  -H "AccessToken: <your-access-token>"

You’ll get the submission’s status, coverages, vehicles, drivers, and account standing. A few things worth knowing right away:

submissionStatus.status reflects the latest transaction (which may be an in-progress endorsement), while coverages reflect the in-force policy — a pending change never blanks out coverage.
submissionStatus.account_standing is Active, Canceled, or Not In Force.
Add ?include=documents to include signed document download URLs.

See the full response in Get Submission Status, and the per-transaction history in List Submission Transactions.

Step 3 — Stop polling: register a webhook

Instead of calling GET /submission/{displayId} on a timer, register an HTTPS endpoint once and Cover Whale will POST you a signed event the instant something changes — a bind completes, a policy enters pending cancellation, and so on.

curl -X POST https://api.coverwhale.dev/v1/webhook-subscriptions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: <your-access-token>" \
  -d '{
    "endpoint_url": "https://hooks.yourapp.com/coverwhale",
    "event_types": ["submission.bind_completed", "submission.canceled", "submission.public_reply"]
  }'

{
  "id": 42,
  "endpoint_url": "https://hooks.yourapp.com/coverwhale",
  "event_types": ["submission.bind_completed", "submission.canceled", "submission.public_reply"],
  "active": true,
  "secret": "whsec_9f2c1e7a4b6d...",
  "created_at": "2026-07-14T12:00:00+00:00"
}

The secret is returned only in this response (and when you rotate it). Store it now — you’ll use it to verify the signature on every delivery, and it is never shown again.

You manage subscriptions entirely yourself — list, update, pause (active: false), delete, or rotate the secret. See Webhook Subscriptions. For the list of event types, payloads, and signature verification, see the Webhooks guide.

Webhook delivery is in early access. You can create subscriptions today; if events aren’t flowing to your account yet, email api-support@coverwhale.com to be switched on. Until then, keep polling as you do now.

Step 4 — Reply back onto a submission (optional)

You can post a note/reply back onto one of your submissions — it shows up for the Cover Whale team on that account:

curl -X POST https://api.coverwhale.dev/v1/submission/2261310/public-reply \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: <your-access-token>" \
  -d '{ "content": "Please add trailer VIN 1UYVS2538 to this policy." }'

See Post a Public Reply.

Tooling

Interactive playground

Every endpoint page has a “Try it” console. Paste your AccessToken once and call the live sandbox straight from the docs — no setup.

Postman collection

Download the Cover Whale API Postman collection and Import → File in Postman. Or Import → Link our OpenAPI spec directly. Set an AccessToken collection variable and you’re ready.

Going live

When your integration is ready, switch the host from api.coverwhale.dev to api.coverwhale.com, swap in your production credentials, and re-register your webhook subscription against production. The paths, headers, and payloads are identical — see the Integration Checklist before you flip over. Questions? api-support@coverwhale.com.

​Getting Started

​Before you start

​Step 1 — Authenticate

​Step 2 — Make your first call

​Step 3 — Stop polling: register a webhook

​Step 4 — Reply back onto a submission (optional)

​Tooling

Interactive playground

Postman collection

​Going live

Getting Started

Before you start

Step 1 — Authenticate

Step 2 — Make your first call

Step 3 — Stop polling: register a webhook

Step 4 — Reply back onto a submission (optional)

Tooling

Going live