Illinois (IL) Title & Registration - Developer Guide

1. Overview & Introduction

The Illinois (IL) Title & Registration API lets you submit and process vehicle title and registration transactions to the Illinois Department of Motor Vehicles (DMV) through Vitu's national platform, and receive back status and confirmation data. It is designed for dealer-facing and service-provider integrations that need to file registration/title work programmatically instead of through a manual portal.

The central domain object is the transaction. A transaction bundles everything the DMV needs to process a title/registration event: the vehicle, the owner(s) and any co-owner, seller, lessor/lessee parties, lienholders, insurance, prior-title details, trade-ins, and the registration action being performed. You create a transaction, and — because processing is handled downstream with the state — the API accepts your submission and works it asynchronously, reporting progress and outcomes back to you.

Transactions are identified two ways: by a Vitu-assigned numeric transaction identifier and by a client-supplied reference number (a UUID). The update operation accepts either identifier in the same path position (see the spec's description of the transactionId path parameter). Understanding this dual-identity model is important for correlation and idempotency (see Behavioral Notes).

Access is over HTTPS against an environment-scoped base URL, with three environments exposed conceptually as production, staging, and test (the spec's servers block enumerates the exact host template and environment values — do not hardcode from memory). All requests are authenticated with OAuth 2.0 client credentials.

Sensitive-data note: transaction payloads and callbacks carry regulated personal data — including Social Security Numbers, dates of birth, FEINs, driver/owner identity, and addresses (see the owner, co-owner, lessee, and seller structures in the ILEVRTransactionDTO). Treat all request and callback traffic as containing PII and handle it accordingly (see Data Sensitivity & Compliance Notes).

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

• OAuth 2.0 client credentials issued by Vitu (see below).
• The ability to reach the environment base URL defined in the spec's servers block.
• A JSON HTTP client capable of Bearer authentication.

Obtain access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal. Use test-environment credentials while integrating.

Minimal happy path

1. Get a token. Request an access token from the OAuth token endpoint using your client credentials and the scope defined by the keycloak security scheme.
2. Create a transaction. Call the transaction-creation operation (operationId: CreateTransaction) with an ILEVRTransactionDTO body. This operation is asynchronous — a successful call is accepted for processing, not completed. See the spec for the exact accepted-response shape and status code.
3. Receive the outcome. Provide a callbackUrl on the create call so Vitu can notify your endpoint as the transaction's status changes (see Asynchronous / Callback Patterns). The callback body is one of the CallbackDTO variants.
4. Amend if needed. If you need to change a submitted transaction, use the update operation (operationId: UpdateTransaction), referencing the transaction by its numeric ID or its reference UUID.

Illustrative request (structure only — consult the spec for the authoritative body): > `> POST <transaction-creation path>?callbackUrl=https://your.app/hooks/evr > Authorization: Bearer <access_token> > Content-Type: application/json > > { ...ILEVRTransactionDTO... } >`

Because the response to a successful create is an acknowledgment, do not treat the HTTP response as the transaction result. The authoritative result arrives via callback (or via your own correlation on the reference number).

3. Authentication & Access Walkthrough

The API uses a single security scheme, defined in the spec as keycloak — an OAuth 2.0 client-credentials flow. The formal definition (token URL, scope name, refresh URL) lives in the spec's securitySchemes; refer to it there rather than copying values. There is no alternative auth mechanism — if you were expecting API keys or a user-interactive flow, they are not offered here.

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

Obtaining a token. Exchange your client ID and secret at the token endpoint named in the security scheme, requesting the scope the scheme declares. You receive a short-lived JWT.

Attaching the token. Send the token as a Bearer credential on every API call. Every operation in the spec requires this scope.

Token lifecycle.

• Tokens expire. Cache and reuse a token until close to its expiry, then request a new one; do not fetch a fresh token per request.
• On a 401 response, obtain a new token and retry once. If the 401 persists with a valid token, treat it as a credential/configuration problem, not a transient error.
• A 403 means you are authenticated but not authorized — new tokens will not help; this is a permissions/entitlement issue to raise with Vitu.

Environment differences. Use the environment-appropriate base URL from the spec's servers block. The token endpoint in the spec points at a test realm; confirm the correct token endpoint per environment before going to production.

4. Key Concepts & Glossary

Transaction — The primary unit of work. Represented on submission by the ILEVRTransactionDTO. It aggregates all parties, the vehicle, and the registration action into one filing.

Transaction type — Categorizes the transaction (see TransactionTypeEnum). It is supplied as a query parameter on both create and update and also appears in some callbacks. Note the type set here overlaps with, but is distinct from, the transaction's application type (below).

Application type — Describes what is being filed (e.g., title-and-registration vs. title-only). Note: the request body's applicationType and the callback's ApplicationTypeEnum enumerate different value sets — treat the request field as the input contract and the callback field as the reported state.

Service type — Selects the level of service for the transaction (see ServiceTypeEnum).

Registration action — Within the transaction, the registration.action field distinguishes a new registration from a plate transfer or a temporary tag. Plate-transfer and replacement scenarios enable additional registration fields (transferred-from vehicle details, plate/sticker numbers, expiration date).

Parties — Structured, largely optional participant blocks: owner, coOwner, seller, lessor, lessee1/lessee2, lienholder1/lienholder2. Individual vs. business identity is driven by the respective *Type enum plus name/SSN or businessName/FEIN fields. The spec's required flags on each nested structure define what is mandatory in a given shape.

Vehicle & trade-ins — The vehicle block carries identity (VIN, make, model, year), sale/lease economics, weights, odometer, and registration dates. tradeInVehicles is a list of vehicles offsetting taxable price.

Identifiers

• Transaction ID — numeric, Vitu-assigned, returned in callbacks.
• Reference number (refNumber) — a client-relevant UUID that also appears in callbacks; use it to correlate asynchronous results.
• Control number — a dealer/deal reference echoed in some callbacks for cross-referencing.

Callback (CallbackDTO) — The asynchronous notification Vitu POSTs to your callbackUrl. It is a polymorphic type discriminated by callbackType, with variants for success, failure, EVR-specific, DMVDESK, and invoiced outcomes. The discriminator tells you which variant (and therefore which fields) to expect.

Lifecycle states — Transaction progress is reported through status enums in callbacks (e.g., TransactionStatusEnum, UniversalStatusEnum, EDealStatus). These are the fields to inspect to determine outcome; consult the spec for their full value sets.

5. Common Use Cases & Integration Patterns

Only two operations exist — create and update — so most integration effort is in constructing the correct payload and reacting to asynchronous outcomes.

Use case A - Submit a new title & registration transaction

1. Acquire a token (Section 3).
2. Build the ILEVRTransactionDTO for the sale: vehicle, owner(s), seller, insurance, and the appropriate applicationType and registration.action.
3. Call CreateTransaction, supplying callbackUrl and the relevant transactionType. Retain the refNumber you sent for correlation.
4. Wait for the status-change callback. Inspect the discriminated callbackType and the reported status fields to determine success or failure.

Use case B - Plate transfer or temporary tag

Same as A, but set registration.action to the transfer/temp-tag variant and populate the transfer-specific fields (transferred-from vehicle, plate number, sticker number, expiration date). The spec's registration structure defines which fields apply.

Use case C - Amend a submitted transaction

1. Reference the transaction by numeric ID or refNumber.
2. Call UpdateTransaction with the revised ILEVRTransactionDTO.
3. Await the follow-up callback for the amended outcome.

Recommended patterns

• Prefer callbacks over polling. There is no read/status operation in this API; the callback is the intended completion signal.
• Correlate on refNumber. Generate and store your own UUID per transaction so inbound callbacks can be matched even before you have the numeric ID.
• Treat create and update as fire-and-confirm. The synchronous response only acknowledges acceptance.

6. Behavioral & Operational Notes

• Asynchronous processing. A successful create/update returns an accepted-for-processing acknowledgment, not a final result. The final result is delivered via callback. Do not block on the HTTP response for the outcome.
• Callback is the source of truth for outcome. Determine success/failure from the callback's discriminated type and its status fields — not from the original acknowledgment.
• Dual identifiers. The update path accepts either the numeric transaction ID or the refNumber UUID in the same position. Ensure your routing/validation handles both forms.
• On-behalf-of header. Both operations accept an optional x-on-behalf-of-user header to attribute the request to a specific user. Use it where your integration acts for multiple end users; omit it otherwise.
• saveForLater / draft transactions. The DTO includes a saveForLater flag, and status enums include draft states. A saved-for-later transaction is not a completed filing; account for draft states in your outcome logic.
• Idempotency. Repeated CreateTransaction calls may create duplicate transactions. Use your refNumber and internal deduplication to avoid double submission.

7. Asynchronous / Callback Patterns

The create and update operations declare an onStatusChange callback delivered to the callbackUrl you supply as a query parameter. The URL must be network-accessible from Vitu's servers and must use HTTP(S) (see the parameter definition in the spec).

Flow

1. You submit a transaction with a callbackUrl.
2. As the transaction's status changes, Vitu POSTs a CallbackDTO to that URL.
3. Your endpoint acknowledges receipt with a success response (see the callback's documented accepted response).

Interpreting callbacks. The payload is polymorphic, discriminated by callbackType (success, failure, EVR, DMVDESK, invoiced). Branch on the discriminator, then read the fields defined for that variant. Correlate using refNumber and/or the numeric transaction ID.

Integrity. The spec notes that when an HMAC key is configured for callbacks, Vitu computes an HMAC/SHA-256 hash and encodes the result (the spec description is truncated). If you enable this, verify the signature on inbound callbacks before trusting them.

​> 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

Three environments are exposed via the server template's env variable: production (api), staging (api-stage), and test (api-test). They are isolated — data and identifiers are not shared. Use api-test for development and integration, api-stage for pre-production validation, and api for live traffic. Access to each is governed by the credentials issued for it (see §3). Refer to the spec for exact URLs.

9. Rate Limiting & Quotas

Responses carry rate-limit headers — RateLimit-Limit and RateLimit-Reset — and a 429 Too Many Requests response includes Retry-After. Read these headers by name rather than hardcoding thresholds; the numeric limits are not fixed in this document and should be read at runtime.

Strategy

• Track RateLimit-Limit / RateLimit-Reset to pace requests proactively.
• On 429, honor Retry-After before retrying. If absent, apply exponential backoff with jitter.
• Rate limiting applies to callback traffic too (the callback responses declare the same headers), so your receiver should also tolerate 429.

10. Error Handling & Troubleshooting

Error responses use the spec's Errors schema (an array of Error) for validation, not-found, and server classes; auth and rate-limit responses use a simpler code/message object. Reference the spec for exact shapes and status codes. Handle by class, not by memorizing individual codes:

Backoff convention. For retryable classes, use exponential backoff with jitter and a bounded attempt count. Stop and surface the failure once the cap is reached or the class is non-retryable.

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks contain regulated personal and financial data — SSNs, dates of birth, FEINs, names, addresses, and vehicle/financial details across the owner, co-owner, seller, lessee, and lessor structures.

• Transmit only over TLS (the base URLs are HTTPS).
• Restrict logging: never log full request/callback bodies containing SSN/DOB/FEIN.
• Secure your callbackUrl endpoint (HTTPS, authenticated/verified via HMAC if enabled).
• Apply least-privilege storage and retention to any persisted transaction data.

This is handling guidance, not legal advice; align with your organization's IL DMV and privacy obligations.

12. Support & Resources

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