Minnesota (MN) Title & Registration - Developer Guide

1. Overview & Introduction

The Minnesota (MN) Title & Registration API submits and processes vehicle title and registration transactions with the Minnesota Department of Motor Vehicles (DMV), and returns transaction status and confirmation data. It lets you originate a title/registration transaction from your own system and track it through DMV processing without operating a manual workflow.

The domain centers on a single core noun: the transaction. A transaction represents one title and/or registration filing and carries the parties and vehicle involved — the owner (and optional co-owner), optional lessee/lessor parties, one or more lienholders, the previous title, and the vehicle itself (see the MNEVRTransactionDTO schema for the composition). A transaction is classified by a transaction type and an application type (for example, title-and-registration versus title-only), and by a service type that governs how much of the filing Vitu performs on your behalf.

Processing is asynchronous. When you submit a transaction, the API accepts it for processing and does the DMV work in the background; results are delivered later. You correlate a submission to its later results using your own reference identifier and the transaction identifier Vitu assigns. Result delivery is via callbacks to a URL you supply (see the CallbackDTO family and Section 8).

The API is served from a single base host with a selectable environment segment (production, stage, and test), defined under servers in the spec. All access is via OAuth 2.0 client-credentials; credentials are issued by Vitu.

Sensitive-data note: transactions carry personally identifiable information — names, dates of birth, driver license numbers, and addresses for owners, co-owners, and lessees. Treat request and callback payloads as regulated PII in transit, at rest, and in logs. See Section 12.

​> Corresponding Title & Registration Notifications product: The Title & Registration Notifications product serves as a complementary offering to this Title & Registration service. Together, the transaction and notification capabilities provide a complete ecosystem for both initiating vehicle transaction 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

• An OAuth 2.0 client (client ID and secret) issued by Vitu.
• The ability to reach the selected environment host (see servers in the spec).
• A network-accessible HTTPS endpoint to receive callbacks, if you want asynchronous results delivered (see Section 8).

Obtain access

Client credentials are obtained from the Key Management area within Vitu's Developer Portal. Use them with the keycloak client-credentials flow defined in the spec's securitySchemes.

Minimal happy path

1. Get a token. Request an access token from the token endpoint in the keycloak security scheme, using your client credentials and the oneapi:access scope.
2. Submit a transaction. Call the transaction-creation operation (operationId: CreateTransaction) with a MNEVRTransactionDTO body. Optionally supply a callback URL so results are delivered to you. The API responds with an accepted for asynchronous processing result — this confirms receipt, not DMV completion.
3. Receive results. Await the callback delivered to your endpoint, or correlate later by your reference identifier. The callback payload indicates outcome and confirmation data.

Refer to the spec for the exact request body, query parameters, headers, and response shapes.

3. Authentication & Access Walkthrough

The API uses a single security scheme, keycloak, of type OAuth 2.0 client-credentials, requiring the oneapi:access scope. This is the only supported scheme — there is no API-key or interactive user-login alternative. The formal definition (token URL, scope name, refresh URL) lives in the spec's securitySchemes; this section covers the operational how-to only.

Obtaining credentials

Client ID and secret are issued by Vitu and are available in the Key Management area of Vitu's Developer Portal.

Obtaining and attaching a token

1. Exchange your client credentials at the token endpoint defined in the scheme for an access token scoped to oneapi:access.
2. Attach the token as a Bearer credential on each API request.

Token lifecycle

• Access tokens expire. Cache and reuse a token until shortly before its expiry, then request a new one.
• On a 401 (unauthorized) response, obtain a fresh token and retry once. If the retry still returns 401, treat it as a credential/configuration problem, not a transient error.
• A 403 means the caller authenticated successfully but lacks permission; do not retry — this requires a change to your entitlements, not a new token.

Environment differences

The environment is selected via the env server variable (production, stage, test). Credentials are environment-specific; confirm which environments your issued credentials are valid for.

4. Key Concepts & Glossary

Transaction — The central resource: one title/registration filing submitted to the MN DMV. Composed of party and vehicle sub-objects (see MNEVRTransactionDTO).

Reference number (refNumber) — A UUID you associate with a transaction. Use it to correlate submissions with callbacks. The update operation accepts either this reference or the assigned integer transaction ID as its path identifier.

Transaction ID — The integer identifier Vitu assigns to a transaction; appears in success/result callbacks.

Transaction type — Classifies the filing channel/family (e.g. EVR, Interstate, DMV Desk). See TransactionTypeEnum for the authoritative values. This influences which callback variant you receive (see Section 8).

Application type — What the filing accomplishes (e.g. title-and-registration, title-only, tax-only). Note the MNEVRTransactionDTO application-type values are defined inline and differ from the ApplicationTypeEnum used in some callbacks — see the flag below.

Service type — Governs how much of the filing Vitu performs (see ServiceTypeEnum, e.g. forms-and-fees versus full service).

Parties — Owner (required in practice for a valid filing), optional co-owner, lessor, lessee(s), and lienholder(s). Each carries identity and address data; see the respective sub-objects in MNEVRTransactionDTO.

Vehicle — The vehicle/vessel being titled/registered, keyed by VIN (or HIN), plus attributes such as make, model, year, weight, and odometer.

Callback — An asynchronous message Vitu posts to your callback URL reporting an outcome or status change. The CallbackDTO family is polymorphic, discriminated by callbackType (see Section 8).

Universal status — A cross-cutting lifecycle indicator (UniversalStatusEnum) present on several callback variants, describing the transaction's disposition.

Control number — A dealer-supplied reference (e.g. stock or deal number) echoed back in results.

5. Common Use Cases & Integration Patterns

Use case A - Submit a new title/registration transaction

1. Obtain a token (Section 3).
2. Generate a refNumber (UUID) on your side to correlate this filing.
3. Call CreateTransaction with a fully populated MNEVRTransactionDTO and a callback URL.
4. Receive the accepted response — the transaction is now queued for DMV processing.
5. Await the result callback and record the assigned transaction ID against your refNumber.

Intent: originate a filing and hand off DMV processing to Vitu.

Use case B - Correct or complete a submitted transaction

1. Identify the transaction by its refNumber or assigned transaction ID.
2. Call UpdateTransaction with the revised MNEVRTransactionDTO.
3. Await the subsequent result callback.

Intent: amend a transaction — for example, after a validation failure callback, or to complete a draft.

Use case C - Draft-then-submit

The transaction body carries a saveForLater flag. Use it to persist an incomplete transaction, then finalize later via UpdateTransaction.

Recommended pattern: callbacks over polling

There is no read/query operation in this spec — no way to fetch a transaction's current state on demand. Result delivery is callback-driven. Design your integration to receive and persist callbacks, and to reconcile them against your stored refNumber. Ensure your callback endpoint is idempotent (see Section 6).

6. Behavioral & Operational Notes

Asynchronous acceptance. The success response to create/update means accepted for processing, not completed. Do not treat it as DMV confirmation. Wait for the callback.

Correlation is your responsibility. Persist your refNumber before submitting. Callbacks carry refNumber and/or the assigned transaction ID; use them to match results to submissions.

Callback idempotency. Design your callback handler to tolerate duplicate deliveries. The spec does not guarantee exactly-once delivery, so deduplicate on refNumber + callbackType + timestamp or equivalent.

Callback signing. When an HMAC key is configured for callbacks, Vitu signs the callback body using HMAC/SHA-256 (base64-encoded). Verify this signature before trusting a callback.

On-behalf-of header. An optional header lets you act on behalf of a specified user ID. Its effect on authorization and record attribution is not described beyond that; confirm expected use with Vitu.

Ordering. No ordering guarantee is stated for callbacks. Do not assume callbacks arrive in causal order; rely on the timestamp field to sequence them.

7. Asynchronous / Callback Patterns

Results are delivered asynchronously to the callback URL you supply on create/update. The onStatusChange callback posts a CallbackDTO to your endpoint; your server should return a success acknowledgment to accept it.

Callback variants

CallbackDTO is polymorphic, discriminated by callbackType. Each variant reports a different outcome or milestone (see the discriminator mapping and the individual DTO schemas):

• Success — filing accepted/processed; carries confirmation data (transaction ID, status, VIN, owner, control number, shipment/indicia, and audit detail).
• Failure — filing rejected; carries error detail.
• EVR / DMV Desk — channel-specific results with their own status fields and error detail.
• Invoiced — fee/invoice detail for one or more transactions.

Correlation

Match each callback to your submission via refNumber (and the assigned transaction ID once known).

Delivery & retry

Your endpoint should return a success status to acknowledge receipt.

​> Corresponding Title & Registration Notifications product: The Title & Registration Notifications product serves as a complementary offering to this Title & Registration service. Together, the transaction and notification capabilities provide a complete ecosystem for both initiating vehicle transaction requests and staying informed of relevant updates through secure, automated notifications. See that product in the Catalog for more details.

8. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit, RateLimit-Reset), and 429 responses carry Retry-After. Read the numeric values from these headers at runtime rather than hard-coding limits — the spec defines the header shapes but not fixed quota values.

Strategy: on 429, wait for the interval indicated by Retry-After (or RateLimit-Reset if Retry-After is absent), then retry with exponential backoff and jitter. Proactively throttle when RateLimit-Limit/RateLimit-Reset indicate you are approaching the limit.

9. Environments & Sandbox Access

The env server variable selects the environment: production, stage, and test (see servers for the authoritative segment values). Use test/stage for integration work and reserve production for live DMV filings. Credentials may differ per environment — obtain and confirm them via the Key Management area of Vitu's Developer Portal.

10. Error Handling & Troubleshooting

Error response bodies use the spec's Errors schema (an array of Error objects, each with a message). Handle errors by class rather than by hard-coding specific codes:

Backoff convention: exponential backoff with jitter for retryable classes; a fixed, low retry cap; and a hard stop that surfaces the failure for manual review.

Note: validation and failure detail may also arrive asynchronously via a failure callback, not only in the synchronous response. Handle both paths.

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks contain regulated PII: full names, dates of birth, driver license numbers and issuing states, and residential/mailing addresses for owners, co-owners, and lessees.

• Transmit only over TLS (enforced by the https host).
• Do not log full request/response or callback bodies; redact PII in logs and error reporting.
• Restrict access to stored transaction data and callback records.
• Verify callback signatures (Section 6) before acting on inbound data.

This is handling guidance, not legal advice.

12. Support & Resources

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