Submissions
A submission represents an insurance application in the Cover Whale system. Each submission moves through a defined lifecycle from initial creation to a bound policy.
Submission Lifecycle
Submitted → In Review → Request to Quote → Quoted → Request to Bind → Bound
| Status | Description |
|---|
| Submitted | Initial application received |
| In Review | Underwriting team is reviewing the submission |
| Request to Quote | Application is ready for quoting |
| Quoted | Pricing has been generated — ready to bind |
| Request to Bind | Bind request submitted by the agent |
| Bound | Policy is bound and active |
Display IDs and Transaction IDs
Each submission has two key identifiers:
- Display ID — The primary submission identifier (e.g.,
2172961). Used in most API calls and visible to agents.
- Transaction ID — Identifies a specific version of the submission. Endorsements and renewals create new transactions under the same display ID.
Think of the Display ID as the “policy number” and the Transaction ID as the “version number.” Most API calls use the Display ID. Transaction IDs are needed when working with specific endorsements or submission versions.
Checking Submission Status
Use the GET /submission/{displayId} endpoint to retrieve the current status and details:
curl -X GET https://app.coverwhale.com/api/v1/submission/2172961 \
-H "Accept: application/json" \
-H "AccessToken: YOUR_ACCESS_TOKEN"
What’s in the Response
The response includes comprehensive submission details:
| Section | Contents |
|---|
| Insured information | Legal name, DBA, DOT number, physical address |
| Coverage details | Requested coverage lines and limits |
| Status | Current submission status |
| Pricing | Premiums, fees, and totals (when quoted) |
| Fleet data | Driver and vehicle information |
Some submission detail fields may vary depending on your API access level. Contact api-support@coverwhale.com if you need access to additional fields. Modifying a Submission
After a submission is created, you can update it using the Submission Data endpoints:
| Operation | Endpoint |
|---|
| Update submission fields | PUT /submission/{displayId}/{transactionId} |
| Add/update/remove vehicles | POST, PUT, DELETE on .../vehicle |
| Add/update/remove drivers | POST, PUT, DELETE on .../driver |
| Add/remove trailers | POST, DELETE on .../trailer |
| Recalculate rates | POST .../recalculate-rates |
| Get taxes and fees | GET .../taxes-fees |
| Download documents | GET .../documents/{type} |
