Reading the record
Carrier Verification API Responses: What to Keep as Evidence
By VerifyCarrier · · 5 min read
A carrier check run through an API is evidence only if you can later show which company was matched, which source said what, as of when, and which parts could not be checked. In VerifyCarrier’s API those answers sit in different fields: the USDOT number for identity, per-source dates and URLs for provenance and freshness, and status values for anything that was not read. The HTTP status code is not one of them. This guide covers what to store and why; the full field reference is in the API documentation.
Sources: VerifyCarrier: API documentation and user guides
Anchor identity to the USDOT number
The basic lookup accepts a USDOT number at /api/lookup/dot/{number} or an MC number at /api/lookup/mc/{number}. An MC lookup asks FMCSA’s QCMobile docket-number endpoint for the carrier, then loads the full record by the USDOT number FMCSA returns, so every successful response carries dot_number. Use that as the key in your own records. A carrier can hold several dockets, listed in docket_numbers, and an MC number identifies an operating authority rather than the company itself.
Name search (/api/search?q=) returns candidates, not an identity. Results are ranked across at most 50 FMCSA name matches; total_is_minimum is true when that cap was reached, and truncated is true when more matches exist than the limit you asked for (1 to 50). There is no page parameter. Choose a candidate only after its address, phone or docket matches the carrier packet, following the same rules as matching government records by hand.
Sources: VerifyCarrier: API documentation and user guides; FMCSA QCMobile API: endpoints, including docket-number lookup
Record where each fact came from
In the basic lookup, metadata.data_source is a single label and metadata.last_updated is the time the response was generated, not a government update time. The provenance is one level down. Each recent_changes flag carries source, source_url and retrieved_at. The enrichment block reports inspections, authority and registration with their own source and source_url, and inspections and authority with an as_of date. basics_as_of dates FMCSA’s BASIC snapshot; when it is more than 24 months old, basics_stale is true and the BASIC fields are null rather than scored.
The evidence endpoint (/api/carrier/{dot}/evidence, API key required) separates response_generated_at from source dates: ucc.censusAsOf, each ucc.sources entry with asOf, retrievedAt and cadence, and source_updated_at, which is null when the upstream update time is unknown. The documentation describes Motus authority data as daily and SMS inspection results as monthly, because FMCSA sources run on different clocks. Keep three dates apart: the date the source describes, the date it was retrieved and the date you decided. Collapsing them is how a review later appears to have seen data it could not have, and keeping them apart is what makes a reconstructable record history possible.
Treat unavailable as unknown, never as clean
Several fields say that a check did not happen. In recent_changes, census.status is checked or unavailable, and authority.status can also be no_record. census.days_without_snapshot counts days in the 90-day window with no snapshot comparison, and census.checked_since is the earliest date the comparison actually covers. In enrichment, unavailable means the source could not be read, while no_record and not_in_source are separate results. not_checked lists checks that were not run; today that is whether the phone is a VoIP line.
The evidence endpoint can return HTTP 200 with status partial. Its carrier block is available, not_found or unavailable; insurance is ok, empty or unavailable, and empty means the source returned no rows, not that the carrier lacks coverage. The documentation states that inspections_24mo and crashes_24mo are currently null with unavailable status, so a missing crash count is not zero. In the basic lookup, risk.tier can be Insufficient data with a null score. A rule that reads only the HTTP code or the tier will pass all of these. Store each as not checked, and map it to the specific reasons an empty carrier result can occur.
Pagination: finish the sequence or discard it
Only the evidence endpoint paginates. UCC filing chains come 25 per page: start at ucc_offset=0, save ucc.batchId, and pass it as ucc_batch while ucc.next_offset is not null. A 409 with ucc_batch_changed means the matched batch changed during the export; discard the pages you have and restart at zero. Insurance policies come up to 100 per page through insurance_offset and insurance.nextOffset. Insurance is a live source, so pages can change during retrieval and the result is not a point-in-time proof of coverage. Out-of-range UCC offsets can reset to zero, so check that each returned offset advances.
Each page is one request against the account allowance. An export that stopped part-way should be stored as incomplete, not as the carrier’s full UCC history. A complete export still needs interpretation: a UCC filing is a lien record, not a finding about the carrier’s finances.
Responses that should stop an automated approval
Each of these means the check did not complete. Store the status code and time as a gap in the review, not as a pass.
- 401: missing, invalid or revoked key. The evidence endpoint and the change-list API require a key; the basic lookup and name search allow limited anonymous use.
- 402 quota_exhausted: the allowance is used up. Anonymous calls are limited to 10 per day; on October 4, 2026 the 402 body gave a resetDate of the next UTC midnight, an offer.url and X-RateLimit-Limit, -Remaining and -Reset headers. The quota is checked before the identifier, so a malformed number also returns 402 once the allowance is spent. Retrying before the reset does not help.
- 403 plan_required: the /api/changes/{kind} change lists are limited to paid plans.
- 404 in the basic lookup: no carrier was found for that number. The evidence endpoint reports not_found per source instead.
- 429: too many requests in a short window. Back off with a bounded delay.
- 5xx or timeout: the check is unconfirmed. Keep the shipment decision open.
What to store with the decision
A recommended minimum, to adapt to your own review policy: the identifier you queried and the dot_number returned; the response time; each source’s URL, as-of and retrieval dates; every status that was unavailable, partial or not checked; the UCC batch ID and whether paging finished; and the decision with who made it and when. The evidence API excludes private notes and decisions, so the decision itself lives in your own system. The review log columns give a tested layout for it.
Sources checked . Procedures are VerifyCarrier’s recommendations; examples are illustrative. How we prepare and correct these guides.