Vehicle History Verification (NMVTIS) - Developer Guide

1. Overview & Introduction

The Vehicle History Verification (NMVTIS) API lets you retrieve title, brand, and historical record data for a vehicle from the National Motor Vehicle Title Information System (NMVTIS). A typical use is confirming a vehicle's prior title status, odometer history, and any salvage, junk, or flood/fire brands before a sale, trade, or titling transaction.

The domain model centers on a single core noun: the inquiry. An inquiry represents one request to look up a specific vehicle (identified by VIN) against NMVTIS. You create an inquiry, the system processes it asynchronously against NMVTIS, and the resulting data becomes available as an inquiry record (structured data) and as a report (a rendered PDF). Each inquiry carries a client-supplied reference number that you control, and a server-assigned inquiry ID. Both can be used to retrieve the inquiry later.

Because processing is asynchronous, an inquiry has an implicit lifecycle: it is created, then processed, then (on success) has record and report data available. The API surfaces completion through an optional callback and through a processed-date/error signal on the inquiry itself (see Behavioral Notes).

Access is environment-scoped. The service is deployed to three conceptual environments — production, staging, and test — selected via the env server variable defined in the spec. Do not hardcode full URLs; resolve them from the spec's servers block.

This API returns data sourced from a federal motor-vehicle title system. Treat responses as potentially sensitive vehicle-history data and handle accordingly (see Data Sensitivity & Compliance Notes).

Corresponding Notifications product: The Vehicle History Verification (NMVTIS) Notifications product serves as a complementary offering to this NMVTIS inquiry service, enabling event-driven notifications related to NMVTIS inquiries. Through subscription-based APIs, users can Add a Subscription for NMVTIS inquiry events, Get Subscription details, Unsubscribe from existing inquiry notifications, and Set Security configurations for subscriptions. Together, the inquiry and notification capabilities provide a complete ecosystem for both initiating vehicle history verification requests and staying informed of relevant updates through secure, automated notifications. See that product in the Catalog for more details.

2. Getting Started / First Call

Prerequisites

• A Vitu-issued OAuth 2.0 client credential (client ID and secret).
• Ability to make server-to-server REST calls and manage a bearer token.
• A VIN to look up.

Obtaining access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal.

Happy-path sequence

1. Obtain an access token using the client-credentials grant (see Authentication).
2. Call the inquiry-creation operation (createInquiry) with a VIN and a client-generated reference number. This returns an inquiry identifier.
3. Wait for processing to complete — either by receiving the callback (if you supply a callback URL) or by polling the inquiry-load operation until it reports a processed state.
4. Once processed, retrieve the structured data via the record-load operation (LoadInquiryRecord), and/or the PDF via the report operation (GetReport).

For exact request and response bodies, refer to the InquiryRequestDTO and InquiryIdResponseDTO schemas in the spec.

3. Authentication & Access Walkthrough

Authentication uses the oneVituOauth security scheme (OAuth 2.0 client-credentials grant) defined in the spec. The spec is authoritative for the token URL and scope; this section covers only operational usage.

Obtaining a token

1. Retrieve your client ID and secret from the Key Management area of Vitu's Developer Portal.
2. Request a token from the token endpoint defined under the oneVituOauth scheme, using the client-credentials grant and requesting the scope named in the spec (oneapi:access).
3. Attach the returned token as a bearer token on every API request.

Token lifecycle

• Access tokens expire. Cache and reuse a token until shortly before its expiry rather than requesting one per call.
• On an authentication failure (the not-authenticated response class), request a fresh token once and retry. If it fails again, treat it as a credential/configuration problem rather than retrying in a loop.
• Distinguish authentication failure (invalid/expired token) from authorization failure (valid token, insufficient permission). The latter will not be resolved by re-issuing a token.

4. Key Concepts & Glossary

Relationships and dependencies

• An inquiry is the parent resource. The record and report are derived children that exist only after the inquiry has been processed.
• An inquiry can be addressed by either its inquiry ID or its reference number (via distinct load operations); these are two keys onto the same resource.
• The record aggregates title, vehicle, brand, and disposition data. Presence of any given sub-section depends on what NMVTIS reported; absence of a section is not an error.

5. Common Use Cases & Integration Patterns

Use case A - One-off vehicle history lookup (polling)

1. createInquiry — submit the VIN and a fresh reference number. Capture the returned inquiry ID.
2. Poll LoadInquiryById (or LoadInquiryByRefNumber) until the inquiry reports a processed state or an error.
3. On success, LoadInquiryRecord for structured data.

Use this when you cannot receive inbound callbacks.

Use case B - Lookup with completion callback (recommended)

1. createInquiry — submit the VIN, reference number, and a callback destination.
2. Receive the transactionCompleted callback carrying the reference number and inquiry ID.
3. Correlate the callback to your original request by reference number, then LoadInquiryRecord and/or GetReport.

See the Vehicle History Verification (NMVTIS) Notifications product for more details on callback capabilities.

Use case C - Retrieve a human-readable report

After an inquiry is processed, call GetReport to obtain the PDF. Use this when a downstream consumer needs a document rather than structured fields. The structured record and the PDF are two representations of the same processed inquiry; retrieve whichever your workflow needs.

Ordering and dependency notes

• Record and report retrieval will not yield meaningful data before processing completes. Always confirm processed state first (via callback or poll).
• Use the reference number as your idempotency/correlation key across your own systems, since you control it.

6. Behavioral & Operational Notes

• Asynchronous processing. Inquiry creation returns an identifier, not results. The record and report become available only after NMVTIS processing completes. Do not assume synchronous availability.
• Completion signal. An inquiry surfaces completion through its processedDate and error fields (see InquiryResponseDTO). Treat a populated processedDate as the completion indicator and a populated error as failure — not the HTTP status of the load call, which reflects only whether the load itself succeeded.
• Two lookup keys, one resource. Loading by inquiry ID and by reference number address the same inquiry. Choose based on which identifier your system holds.
• Partial record data is normal. Record sub-sections (previous title, brands, disposition, etc.) reflect what NMVTIS reported. Missing sections indicate no data reported, not an error.

7. Environments & Sandbox Access

Three environments are available via the env server variable: production, staging, and test. Resolve base URLs from the spec's servers block rather than hardcoding them. Use the test/staging environments for integration development, and confirm the corresponding token endpoint per environment. Environment access is governed by the credentials issued from the Developer Portal's Key Management area.

8. Rate Limiting & Quotas

The API can return a rate-limit response (the too-many-requests class, TooManyRequests). When you receive it, back off and retry after the limit window resets. The spec does not define specific numeric limits or a documented Retry-After header; if present, honor a retry header returned in the response. Otherwise, apply exponential backoff (see the agent failure-handling rules). Do not treat rate-limit responses as terminal.

9. Error Handling & Troubleshooting

All error responses use the Errors schema (an array of Error objects) defined in the spec. Handle by class rather than by specific code:

Distinguish transport-level failures of a load call from an inquiry-level failure reported in the inquiry's error field — the latter means processing failed even though the load succeeded.

10. Data Sensitivity & Compliance Notes

This API returns NMVTIS-sourced vehicle-title and history data, including odometer readings and salvage/junk brands. Treat responses as sensitive:

• Retrieve and store only what your use case requires, and protect stored records and PDFs at rest and in transit.
• Restrict access to inquiry results to authorized users within your system.

This is handling guidance, not legal advice. NMVTIS data use is subject to federal and program-level rules; confirm your permitted-use obligations with Vitu and the relevant authorities.

11. Support & Resources

For any API assistance, contact Vitu's API support team at [email protected].