> ## 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.
# Getting Started
> From zero to your first Cover Whale API call — and your first webhook — in about 10 minutes
# 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](/api-reference/authentication/get-authentication-token) has an interactive **"Try it"** console — the fastest way to experiment while you read. Prefer Postman? Jump to [Tooling](#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](mailto: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](https://webhook.site) tool is fine for a first test.
## Step 1 — Authenticate
Exchange your credentials for an access token. It's good for one hour.
```bash theme={null}
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"
}'
```
```json theme={null}
{
"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](/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.
```bash theme={null}
curl https://api.coverwhale.dev/v1/submission/2261310 \
-H "Accept: application/json" \
-H "AccessToken: "
```
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](/api-reference/submissions/get-submission-status), and the per-transaction history in [List Submission Transactions](/api-reference/submissions/get-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.
```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/webhook-subscriptions \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "AccessToken: " \
-d '{
"endpoint_url": "https://hooks.yourapp.com/coverwhale",
"event_types": ["submission.bind_completed", "submission.canceled", "submission.public_reply"]
}'
```
```json theme={null}
{
"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](/api-reference/webhooks/create-webhook-subscription). For the list of event types, payloads, and signature verification, see the [Webhooks](/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](mailto: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:
```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/submission/2261310/public-reply \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "AccessToken: " \
-d '{ "content": "Please add trailer VIN 1UYVS2538 to this policy." }'
```
See [Post a Public Reply](/api-reference/submissions/post-submission-public-reply).
## Tooling
Every endpoint page has a **"Try it"** console. Paste your `AccessToken` once and call the live sandbox straight from the docs — no setup.
Download the [Cover Whale API Postman collection](/cover-whale-api.postman_collection.json) 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](/integration-checklist) before you flip over.
Questions? [api-support@coverwhale.com](mailto:api-support@coverwhale.com).