> ## 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. # Pre-Screen a DOT Number > Run Cover Whale's DOT pre-screen for a carrier and get back the eligibility verdict plus a small pre-fill payload. This is the same check the Cover Whale submission page runs when an agent types in a DOT number, exposed so you can pre-qualify a carrier before building a quote. ### What `eligible` means `eligibility.eligible` is `true` when **no decline rule fired**. It does **not** mean the submission will be accepted. A carrier can come back `eligible: true` and still carry warnings that require underwriting review — see the example response below, where the carrier's federal registration is inactive and its operating authority could not be verified, yet `eligible` is `true`. Treat `eligible: true` as "clear to quote", never as "clear to bind". ### Declines versus warnings `decline_reasons` and `warnings` are separate lists and behave differently: - **`decline_reasons`** — a hard stop. Any entry here sets `eligible` to `false`. - **`warnings`** — advisory. Warnings never change `eligible`. They tell you what an underwriter will look at, and some are phrased "Requires underwriting review". The same situation never appears in both lists. Every rule is permanently one or the other; the two enumerations are in the response-field descriptions below. ### Rate limits Two ceilings apply, both counted against your own account rather than a shared network address, so another partner's traffic can never consume your allowance: - **60 requests per minute** - **250 requests per day** Either ceiling returns `429` with a `Retry-After` header giving the seconds to wait, and a body carrying `retry_after`, a human-readable `retry_after_human`, and the `scope` that was limited. Sustained breaches add a temporary block, which returns the same `429` shape with a longer `retry_after`. Batch workloads are supported inside those ceilings. If 250 screens a day is too tight for your volume, contact us — the limit is raisable per account without a code change. ### Two "no answer" cases you must handle separately - `service_available: false` with a `503` — the federal data source is temporarily unreachable. Retry later; the carrier may be perfectly fine. - `dot_not_found: true` with a `200` — the request succeeded and our carrier data provider holds no record for this DOT yet; `warnings` will carry `fmcsa_record_pending`. This is an answer, not a failure, and is **not** a `404`. You can continue and supply the carrier details yourself; the DOT is re-checked automatically when you quote. ### What this endpoint never returns Federal safety scores, out-of-service percentages, inspection and crash counts, addresses beyond the state, and the evidence behind any cancellation-related decline are all deliberately withheld. The message in `decline_reasons` is the whole of what is disclosed. Where a carrier is already bound elsewhere, the other agency is never named. ## OpenAPI ````yaml get /submission/pre-screen/{dotNumber} openapi: 3.0.0 info: title: Cover Whale API V1 contact: name: Cover Whale API Team version: '1.0' servers: - url: https://api.coverwhale.dev/v1 security: - AccessToken: [] tags: - name: Authentication description: Authenticating & Interacting with the API paths: /submission/pre-screen/{dotNumber}: get: tags: - Quoting summary: Pre-Screen a DOT Number description: >- Run Cover Whale's DOT pre-screen for a carrier and get back the eligibility verdict plus a small pre-fill payload. This is the same check the Cover Whale submission page runs when an agent types in a DOT number, exposed so you can pre-qualify a carrier before building a quote. ### What `eligible` means `eligibility.eligible` is `true` when **no decline rule fired**. It does **not** mean the submission will be accepted. A carrier can come back `eligible: true` and still carry warnings that require underwriting review — see the example response below, where the carrier's federal registration is inactive and its operating authority could not be verified, yet `eligible` is `true`. Treat `eligible: true` as "clear to quote", never as "clear to bind". ### Declines versus warnings `decline_reasons` and `warnings` are separate lists and behave differently: - **`decline_reasons`** — a hard stop. Any entry here sets `eligible` to `false`. - **`warnings`** — advisory. Warnings never change `eligible`. They tell you what an underwriter will look at, and some are phrased "Requires underwriting review". The same situation never appears in both lists. Every rule is permanently one or the other; the two enumerations are in the response-field descriptions below. ### Rate limits Two ceilings apply, both counted against your own account rather than a shared network address, so another partner's traffic can never consume your allowance: - **60 requests per minute** - **250 requests per day** Either ceiling returns `429` with a `Retry-After` header giving the seconds to wait, and a body carrying `retry_after`, a human-readable `retry_after_human`, and the `scope` that was limited. Sustained breaches add a temporary block, which returns the same `429` shape with a longer `retry_after`. Batch workloads are supported inside those ceilings. If 250 screens a day is too tight for your volume, contact us — the limit is raisable per account without a code change. ### Two "no answer" cases you must handle separately - `service_available: false` with a `503` — the federal data source is temporarily unreachable. Retry later; the carrier may be perfectly fine. - `dot_not_found: true` with a `200` — the request succeeded and our carrier data provider holds no record for this DOT yet; `warnings` will carry `fmcsa_record_pending`. This is an answer, not a failure, and is **not** a `404`. You can continue and supply the carrier details yourself; the DOT is re-checked automatically when you quote. ### What this endpoint never returns Federal safety scores, out-of-service percentages, inspection and crash counts, addresses beyond the state, and the evidence behind any cancellation-related decline are all deliberately withheld. The message in `decline_reasons` is the whole of what is disclosed. Where a carrier is already bound elsewhere, the other agency is never named. operationId: preScreenDot parameters: - name: Accept in: header required: true schema: type: string example: application/json - name: AccessToken in: header required: true schema: type: string example: eyJraWQiOiJnRk5oTTh2RnRKWXVDVXU1S........ - name: dotNumber in: path description: >- The carrier's DOT number: 1 to 8 digits, and not zero. Anything else returns `400` without a screen being run. required: true schema: type: string pattern: ^\d{1,8}$ example: '1234456' responses: '200': description: >- Screen completed. Check `eligibility.eligible`, and read `warnings` even when it is `true`. content: application/json: schema: type: object properties: dot_number: description: The DOT number you asked about, echoed back. type: string example: '1234456' legal_name: description: >- Carrier legal name. May be null when the federal record is incomplete. type: string nullable: true example: BENNIE SAYLOR garaging_state: description: >- Two-letter state of the carrier's physical address. May be null. type: string nullable: true example: OH num_power_units: description: >- Declared power-unit count. May be 0 or null — 0 is a real declared value, not missing data. type: integer nullable: true example: 0 years_business: description: >- Years in business. May be null when the federal record does not carry it. type: integer nullable: true example: null eligibility: description: >- The verdict. `eligible` is true when `decline_reasons` is empty, and is unaffected by `warnings`. type: object properties: eligible: description: >- True when no decline rule fired. Clear to quote — not clear to bind. type: boolean example: true decline_reasons: description: >- Hard stops. Any entry sets `eligible` to false. Possible rules: - `basic_scores_exceeded` — Too many federal safety categories exceed their thresholds. - `fmcsa_violations_11mo` — Critical federal violations exceed the 11-month threshold. - `fmcsa_violations_24mo` — Critical federal violations exceed the 24-month threshold. - `excessive_red_flags` — Federal red-flag violations exceed the allowed count. - `ineligible_state` — The garaging state is one Cover Whale is not licensed in. - `unlisted_fleet_exposure` — Federal inspection records show more power units operating under this DOT than its registration declares. - `hazmat_compliance_exposure` — Hazardous-materials compliance exposure. - `chameleon_shared_fleet` — Reported equipment does not align with federal inspection records, which show vehicles operating under multiple DOT numbers. - `chameleon_prior_cancellation` — Shares identifying information with a carrier previously cancelled by Cover Whale for cause. - `dot_blocked` — This DOT is on Cover Whale's exclusion list. Takes precedence over every other outcome, including an unavailable data source. type: array items: type: object properties: rule: description: >- Stable machine-readable identifier. Safe to branch on. type: string example: inactive_carrier message: description: >- Human-readable explanation, suitable for showing to an agent. type: string example: >- Carrier MCS-150 status is not active (status: I). Requires underwriting review. warnings: description: >- Advisory only — never changes `eligible`. These are what an underwriter will examine. Possible rules: - `inactive_carrier` — Federal registration status is not active. - `carrier_data_unavailable` — Registration data could not be retrieved, so carrier status could not be verified. - `inactive_authority` — Operating authority is not active. - `pending_authority` — Operating authority is not yet active but an application is pending. - `authority_data_unavailable` — Operating authority data could not be retrieved. - `new_venture` — Less than one year in business. - `large_fleet` — Fleet size exceeds the reviewed threshold. - `hazmat_carrier` — Flagged for hazardous-materials transport. - `excluded_commodity` — Hauls a commodity outside normal appetite. - `ineligible_entity_name` — The entity name contains terms that need review. - `recent_crashes` — Federally reportable crashes in the last 36 months. - `high_oos_rate` — Out-of-service rate above the national average. - `active_investigations` — Open federal investigations on file. - `excessive_cancellations` — Several distinct cancelled policies in the last 24 months. - `fmcsa_record_pending` — Our carrier data provider has no record for this DOT yet. Accompanies `dot_not_found: true`. Newly issued or recently updated federal registrations can take several days to reach the provider's feed; if the number is correct you can continue and supply the carrier details yourself, and the DOT is re-checked automatically when you quote. - `already_bound_other_agency` — Already bound with another agency: you can quote, but a signed Broker of Record is required to bind. The other agency is never identified. type: array items: type: object properties: rule: description: >- Stable machine-readable identifier. Safe to branch on. type: string example: inactive_carrier message: description: >- Human-readable explanation, suitable for showing to an agent. type: string example: >- Carrier MCS-150 status is not active (status: I). Requires underwriting review. service_available: description: >- False when the federal data source could not be reached. A screen with this false is returned as a 503, except when the DOT is on the exclusion list, which takes precedence. type: boolean example: true dot_not_found: description: >- True when the request succeeded but our carrier data provider holds no record for this DOT yet. A 200, not a 404 — newly issued or recently updated federal registrations can take several days to reach the provider's feed. When this is true, `warnings` carries `fmcsa_record_pending` with the detail. This is not a decline: you can continue and supply the carrier details yourself, and the DOT is re-checked automatically when you quote. type: boolean example: false screened_at: description: >- When the screen ran. ISO 8601 with offset. Use it for your own caching and audit. type: string format: date-time example: '2026-10-21T00:25:33+00:00' example: dot_number: '1234456' legal_name: BENNIE SAYLOR garaging_state: OH num_power_units: 0 years_business: null eligibility: eligible: true decline_reasons: [] warnings: - rule: inactive_carrier message: >- Carrier MCS-150 status is not active (status: I). Requires underwriting review. - rule: authority_data_unavailable message: >- Operating authority data is not available for this DOT number. Unable to verify active authority. - rule: already_bound_other_agency message: >- This DOT is already bound with another agency. You can quote, but a signed Broker of Record (BOR) is required to bind. service_available: true dot_not_found: false screened_at: '2026-10-21T00:25:33+00:00' '400': description: The DOT number is not 1-8 digits, or is zero. No screen is run. content: application/json: schema: type: object properties: error: type: string example: Invalid DOT number. Must be 1-8 digits. '401': description: Unauthorized — missing or invalid AccessToken '429': description: >- Rate limit exceeded — either more than 60 requests in a minute or more than 250 in a day on your account, or a temporary block after sustained breaches. The `Retry-After` header gives the seconds to wait; the body repeats it as `retry_after`, adds a human-readable `retry_after_human`, and names the limited `scope`. content: application/json: schema: type: object properties: error: type: string example: Rate limit exceeded. Temporarily banned. retry_after: description: Seconds to wait before retrying. type: integer example: 3600 retry_after_human: description: The same wait, phrased for a person. type: string example: 1 hour scope: description: Which limit was hit. type: string example: pre_screen '500': description: Unexpected failure. Retry; contact Cover Whale if it persists. content: application/json: schema: type: object properties: error: type: string example: Pre-screen failed. Please try again. '503': description: >- The federal data source is temporarily unreachable. Retry shortly — this says nothing about the carrier. content: application/json: schema: type: object properties: error: type: string example: >- Our data provider is temporarily unavailable. Please try again in a few minutes, or contact us for assistance. components: securitySchemes: AccessToken: type: apiKey description: >- JWT returned as AccessToken by the /authentication endpoint (the Cognito ID token carrying the email claim). It expires after 3600 seconds. name: AccessToken in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.