Skip to main content

​
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

Submissions can also be Declined at the review or quoting stages if they don’t meet underwriting criteria. See Decline Reasons for common causes.

​
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:

​
What’s in the Response

The response includes comprehensive submission details:
Some submission detail fields may vary depending on your API access level. Contact api-support@coverwhale.com if you need access to additional fields.

​
Including Documents

By default, GET /submission/{displayId} returns status and submission data only — no documents. This keeps the endpoint fast (documents require generating signed S3 links, which is expensive on every call). If you poll for status, this is the response you want. To get documents, add ?include=documents:
The response then contains a documents section with signed download URLs, keyed by transaction — new_business, endorsement_1, endorsement_2, and so on — so you get the documents for every transaction on the policy in one call, without needing to know which endorsement is latest. The signed URLs are short-lived; fetch them when you need them rather than caching.
Poll status without include (fast), and request ?include=documents only when you actually need to pull files. Better still, move status polling to webhooks and reserve the API for on-demand document fetches.

​
Modifying a Submission

After a submission is created, you can update it using the Submission Data endpoints: See the Submission Data section in the API Reference for full details.