Wisconsin (WI) Title & Registration - Developer Guide

1. Overview & Introduction

The Wisconsin (WI) Title & Registration API submits title and registration transactions to the Wisconsin Department of Motor Vehicles (DMV) and returns transaction status and confirmation data. It is intended for developers integrating Vitu's electronic vehicle registration (EVR) capabilities into dealer, lender, or service-provider systems.

The core domain object is the transaction: a single title-and-registration submission carrying the vehicle, owner, seller, lienholder, lessor/lessee, and prior-title details required by the WI DMV. A transaction moves through a lifecycle from creation to completion, during which the DMV and Vitu processing pipeline may accept it, surface audit findings, assign plates and control numbers, generate shipment/indicia data, and eventually invoice associated fees. The transaction submission body is defined by the WIEVRTransactionDTO schema.

Processing is asynchronous. Both the create and update operations acknowledge acceptance immediately and perform the actual DMV processing afterward. Results and lifecycle changes are delivered out-of-band through callbacks (see the CallbackDTO family and Section 9). A transaction is identified by an integer transaction ID and by a UUID reference number (refNumber); either may be used to address an existing transaction.

The API is served from environment-specific base URLs distinguished by an environment variable (production, staging, and test). See the servers block in the spec for the exact URL template and environment values, and Section 8 for the environment model. All access requires OAuth 2.0 client-credentials authentication.

Data sensitivity: transaction payloads contain personally identifiable information (owner/lessee names, dates of birth, driver license numbers, FEINs, and addresses). Treat request and callback data as sensitive. 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

• A Vitu-issued OAuth 2.0 client-credentials credential set (client ID and secret).
• Network access to the appropriate environment base URL (see the spec's servers block).
• The ability to receive HTTPS callbacks if you want asynchronous results delivered (optional but recommended — see Section 9).

Obtain access

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

Minimal happy path

1. Get a token. Exchange your client credentials for an access token at the token endpoint defined by the keycloak security scheme, requesting the oneapi:access scope. (See Section 3.)
2. Submit a transaction. Call the transaction-creation operation (CreateTransaction) with a WIEVRTransactionDTO body. Optionally supply a callback URL so results are delivered asynchronously. A successful call is acknowledged as accepted for asynchronous processing — it does not mean DMV processing is complete.
3. Receive the outcome. Await the callback(s) delivered to your callback URL, or correlate later status by the refNumber you supplied / received. Interpret the outcome from the callback payload's status fields, not from the acceptance acknowledgment. (See Sections 6 and 9.)

Consult the spec for the exact request body shape and response definitions.

3. Authentication & Access Walkthrough

Authentication uses OAuth 2.0 client credentials. The formal definition — token URL, flow, and scope — lives in the spec under the keycloak security scheme. This section covers only the operational how-to.

Obtaining credentials

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

Obtaining a token

Request an access token from the token endpoint defined in the keycloak scheme, using the client-credentials grant and the oneapi:access scope. The service issues JWTs and follows RFC 8725 best practices.

Attaching the token

Send the issued token as a Bearer token in the Authorization header on every API call.

Token lifecycle

• Tokens are short-lived; cache and reuse a token until shortly before expiry rather than requesting one per call.
• On a 401 response, obtain a fresh token and retry once. Persistent 401 indicates a credential or scope problem, not a transient failure. A 403 indicates the caller is authenticated but not authorized — do not retry; contact support.

Only one scheme

Only the keycloak OAuth 2.0 client-credentials scheme is defined. There is no API-key or alternate auth path — do not expect one.

4. Key Concepts & Glossary

Transaction — The central unit of work: a WI title-and-registration submission. Its input shape is WIEVRTransactionDTO. Created via CreateTransaction, modified via UpdateTransaction.

Reference number (refNumber) — A UUID identifying a transaction. Can be supplied by the caller and is echoed in callbacks. Usable interchangeably with the integer transaction ID to address an existing transaction.

Transaction ID — The integer identifier assigned within the Vitu system, returned in callback payloads.

Transaction type (TransactionTypeEnum) — Classifies how the transaction is processed within the platform (e.g., EVR, interstate, DMV-desk). Controls which callback variant applies. See the spec for the current value set.

Application type — The DMV filing intent (e.g., title-and-registration, title-only). Note there are two related but distinct enumerations: the top-level applicationType on the submission body and the ApplicationTypeEnum referenced in the success callback. Consult each in the spec; do not assume identical value sets.

Service type (ServiceTypeEnum) — Selects the level of service requested (forms-and-fees vs. full service).

Parties — The submission models several related parties: owner, seller (dealer), lessor, lessee(s), and lienholder. Presence and required sub-fields depend on the nature of the deal (purchase vs. lease, individual vs. business). The spec's nullable/required flags govern which are needed in a given context.

Vehicle — The vehicle/vessel being titled, plus optional trade-in vehicles.

Callback — An asynchronous notification about a transaction, modeled by CallbackDTO and its discriminated variants (success, failure, DMV-desk, EVR, invoiced). The callbackType discriminator selects the variant. Callbacks carry the outcome data (assigned plate, control number, shipment/indicia, audit findings, invoiced fees) the synchronous acknowledgment does not.

Status fields — Several status enumerations describe different facets of lifecycle: TransactionStatusEnum (overall processing state), UniversalStatusEnum (a platform-wide status), EDealStatus (DMV-desk deal state). These are distinct dimensions — see the spec for each value set.

Indicia / shipment (IndiciaDTO) — Fulfillment/shipping information (carrier, tracking, ship-to) associated with a completed transaction.

Relationships & dependencies

• A transaction must be created before it can be updated. UpdateTransaction requires an existing transaction addressed by ID or refNumber.
• Callbacks are children of a transaction, correlated back to it by refNumber (and transactionId where present).
• The applicable callback variant is tied to the transaction's type and lifecycle stage.

5. Common Use Cases & Integration Patterns

Scenario A - Submit a new WI title/registration transaction

1. CreateTransaction with a WIEVRTransactionDTO body, including a caller-generated refNumber and a callbackUrl.
2. Store the refNumber locally as your correlation key.
3. Await the asynchronous callback(s) to learn the DMV outcome.

Intent: The create call only enqueues work. Persist your correlation key before relying on the callback so late or retried callbacks can be matched.

Scenario B - Correct or complete a transaction

1. UpdateTransaction, addressing the transaction by its ID or refNumber.
2. Await callbacks reflecting the revised processing.

Intent: Use update to amend a previously submitted transaction — for example, in response to a failure or audit callback that indicates fixable issues.

Scenario C - Draft / save-for-later

The submission body exposes a save-for-later indicator. Submit an incomplete transaction to persist a draft, then complete it later via update.

Intent: Supports multi-step data collection without committing a full DMV filing.

Recommended patterns

• Prefer callbacks over polling. The API is asynchronous and callback-driven; supply a callbackUrl on submission. No dedicated read/status operation is defined in this spec — see the FLAG below.
• Idempotency via refNumber. Generate and reuse a stable refNumber per logical transaction so retries and updates address the same record.

6. Behavioral & Operational Notes

• Acceptance ≠ completion. Both operations acknowledge with an accepted-for-async-processing response. This confirms only that the submission was queued, not that the DMV accepted or completed it. Determine the real outcome from callbacks.
• Outcome arrives via callback only. Assigned plate, control number, audit messages/errors, shipment/indicia data, and invoiced fees are delivered in callback payloads, not in the operation response.
• Discriminated callback variants. The callback body is a oneOf selected by the callbackType discriminator. Route handling on that discriminator; the same transaction may produce different callback variants across its lifecycle (e.g., success, then invoiced).
• on-behalf-of header. Both operations accept an optional header identifying the user on whose behalf the request is made. Supply it when acting for a specific end user; see the spec for its exact name and type.

7. Asynchronous / Callback Patterns

The API is callback-driven. When you supply a callbackUrl on a create or update operation, Vitu POSTs a CallbackDTO to that URL as the transaction progresses.

• Endpoint requirements. The callback URL must be an HTTPS endpoint reachable from Vitu's servers.
• Payload. Each callback is one of the discriminated CallbackDTO variants, selected by callbackType. It carries a timestamp and, in most variants, the refNumber and/or transaction ID.
• Correlation. Match callbacks to your originating request by refNumber (primary) and transaction ID where present.
• Acknowledgment. Your endpoint should return a success response to indicate the callback was accepted; the callback definition documents the expected response codes.
• Integrity/HMAC. If an HMAC key is configured for callbacks, Vitu computes an HMAC-SHA256 signature and encodes the result (base-encoded) so you can verify authenticity.

​> 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. Environments & Sandbox Access

The API exposes three environments through the environment variable in the spec's servers block: a production environment, a staging environment, and a test environment. Use the test environment for integration development and the staging environment for pre-production validation; reserve production for live submissions. Refer to the spec for the exact URL template and environment identifiers.

Credentials are environment-scoped and issued via the Key Management area of Vitu's Developer Portal.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit and RateLimit-Reset), and a rate-limited response (HTTP 429) additionally carries a Retry-After header. Read these headers rather than assuming fixed limits — the numeric values are set by the service and are not published in this guide.

Handling strategy:

• On 429, wait for the interval indicated by Retry-After before retrying.
• Use exponential backoff with jitter for repeated limiting.
• Proactively throttle when RateLimit-Limit / RateLimit-Reset indicate you are approaching the ceiling.

10. Error Handling & Troubleshooting

Handle errors by class, not by memorizing individual codes. The structured error body is defined by the Errors / Error schemas (used for bad-request, not-found, and server errors); some auth and rate-limit responses use a simpler code/message object. Consult the spec for exact shapes.

Backoff convention: exponential backoff with jitter for retryable classes (429, 500); a single immediate retry after refresh for 401. Do not retry 400/403/404 without changing the request.

11. Data Sensitivity & Compliance Notes

Transaction submissions and callbacks contain PII — owner and lessee names, dates of birth, driver license numbers, FEINs, and physical/mailing addresses — as well as vehicle and financial details.

• Transmit only over TLS (enforced by the HTTPS-only base URLs and callback URL requirement).
• Restrict storage and logging of request/callback bodies; avoid logging PII fields in plaintext.
• Verify callback authenticity (HMAC) before trusting inbound payloads, and ensure your callback endpoint is not publicly enumerable.
• Scope credential distribution narrowly and rotate secrets via Key Management.

This is handling guidance, not legal advice; confirm regulatory obligations for handling DMV/PII data with your own compliance function.

12. Support & Resources

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