Maryland (MD) Title & Registration - Developer Guide

1. Overview & Introduction

The Maryland (MD) Title & Registration API submits and processes vehicle title and registration transactions with the Maryland Department of Motor Vehicles (DMV) and returns transaction status and confirmation data. It is intended for dealers, service providers, and software vendors who need to file MD title/registration work programmatically instead of through manual DMV workflows.

The central noun is the transaction — a single title/registration filing that carries all the data the DMV needs: vehicle details, owner and co-owner, optional lessee/lessor and lienholder parties, insurance, prior-title information, and any trade-ins. A transaction moves through a lifecycle after submission (it is accepted for asynchronous processing, then progresses toward completion or failure). The transaction's shape is defined by the MDEVRTransactionDTO schema; its lifecycle state is reported back through status fields and callbacks, not synchronously in the submission response.

Processing is asynchronous. The submission operations acknowledge receipt (they do not return a finished result inline). Outcomes — success, failure, DMV-desk progress, EVR-specific data, and invoicing — are delivered later, either by polling on your side or via the callback mechanism the spec models under onStatusChange (see Asynchronous / callback patterns).

Environments follow a single conceptual model: one base host per environment (production, stage, test), selected by an environment variable in the server URL. Use the test environment for integration work and reserve production for live filings. Exact hostnames live in the spec's servers block — do not hardcode them from memory.

Access and sensitive data. All operations require OAuth 2.0 (see below). Transactions contain personally identifiable information (names, addresses, dates of birth, driver license numbers) and financial data (selling price, lien amounts, fees). Treat all payloads and callbacks as sensitive; 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

• Vitu-issued OAuth 2.0 client credentials (client ID and secret).
• The ability to reach the environment host and the token endpoint over HTTPS.
• A prepared transaction payload conforming to MDEVRTransactionDTO.
• (Recommended) A network-accessible HTTPS endpoint to receive callbacks, if you want asynchronous outcome delivery.

Obtain access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal. The scope required by every operation is oneapi:access (defined under the keycloak security scheme in the spec).

Minimal happy path

1. Get a token. Exchange your client credentials at the token endpoint for an access token (client-credentials grant).
2. Submit a transaction. Call the transaction-creation operation (CreateTransaction) with an MDEVRTransactionDTO body, targeting the test environment. Optionally supply a callback URL and the transaction type.
3. Receive acknowledgment. A successful call is accepted for asynchronous processing — it confirms receipt, not completion.
4. Learn the outcome. Handle the callback delivered to your endpoint (or coordinate with support, given no retrieval operation exists — see the note in §1).

Illustrative token request

curl -X POST "$TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=oneapi:access"

Use the returned access token as a Bearer token on the submission call. Refer to the spec for the request body schema and the exact response contract.

3. Authentication & Access Walkthrough

Authentication uses OAuth 2.0 client credentials. The formal definition lives in the spec under the keycloak security scheme; do not re-derive it from this text.

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

Obtaining a token. POST your client credentials to the token endpoint declared in the security scheme, requesting the oneapi:access scope. You receive a short-lived access token.

Attaching the token. Send the token as an Authorization: Bearer <token> header on every API call. All operations declare the oneapi:access requirement.

Token lifecycle.

• Access tokens expire. Cache a token and reuse it until shortly before expiry, then request a new one.
• On a 401 (unauthorized) response, obtain a fresh token and retry once. Do not loop indefinitely.
• A 403 means the caller is authenticated but not authorized for the operation — this is not fixable by refreshing the token; escalate to support.

Environment differences. The token endpoint and API host are environment-specific. Ensure your token was issued by the same environment's authorization server that you are calling.

4. Key Concepts & Glossary

Identifier relationship. A transaction is identifiable by either its numeric transactionId or its UUID refNumber; the update operation's path parameter accepts either. Supply and retain a refNumber at creation so you can correlate later callbacks.

Callback subtypes. CallbackDTO is a discriminated union keyed by callbackType. Each subtype (success, failure, DMV-desk, EVR, invoiced) carries a different payload. Branch on the discriminator; the spec defines each subtype's fields.

5. Common Use Cases & Integration Patterns

Use case A - File a new title/registration transaction

1. Authenticate (§3).
2. Build an MDEVRTransactionDTO, including a client-generated refNumber for correlation.
3. Call CreateTransaction, optionally supplying a callback URL and transaction type.
4. Receive the acceptance acknowledgment.
5. Wait for a callback (or reconcile with support) to learn the outcome, correlating on refNumber.

Use case B - Correct or amend a submitted transaction

1. Authenticate.
2. Call UpdateTransaction, addressing the transaction by transactionId or refNumber, with the revised MDEVRTransactionDTO.
3. Receive the acceptance acknowledgment.
4. Wait for a follow-up callback reflecting the updated processing.

Use case C - Draft / save-for-later

The transaction carries a saveForLater flag. Use it to submit a draft that is not yet ready for full processing, then complete it later via update. Confirm the exact behavior of drafts (e.g. whether they are validated) with the API owner.

Recommended patterns

• Prefer callbacks over polling — there is no retrieval operation, so callbacks are the primary outcome channel. Supply a callback URL on creation.
• Always send a refNumber so every callback can be matched to its originating request.
• Treat submission as fire-and-then-reconcile, not request/response. Do not block a user flow on the acknowledgment; drive UI state from callbacks.

6. Behavioral & Operational Notes

• Asynchronous processing. Submission and update are accepted for background processing. The acknowledgment is not the final result; the transaction's real status arrives later via callback. Design for eventual consistency.
• Correlation is your responsibility. Because there is no read endpoint, you must persist the refNumber (and, once known, transactionId) and match incoming callbacks to your records.
• Callback authenticity. When an HMAC key is configured for callbacks, the payload is signed using HMAC/SHA-256 (base64-encoded), per the callback description in the spec. Verify the signature before trusting a callback.

7. Asynchronous / Callback Patterns

The API models an onStatusChange callback: when you supply a callback URL on submission, Vitu POSTs a CallbackDTO to that URL as the transaction's state changes. Your endpoint must be network-accessible over HTTP(S) and should return a success acknowledgment to confirm receipt.

Flow.

1. Supply a callback URL when creating (or updating) a transaction.
2. Vitu processes the transaction asynchronously.
3. On each state change, Vitu POSTs a CallbackDTO subtype to your URL.
4. Your endpoint verifies the payload (HMAC, when configured), records the state, and returns success.

Correlation. Match callbacks to originating requests using refNumber (and transactionId once assigned). Branch handling on the callbackType discriminator.

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

Operations return rate-limit headers (RateLimit-Limit, RateLimit-Reset) on responses, and Retry-After on throttled (429) responses. Read these headers rather than hardcoding limits — the numeric values live in the spec and may change.

Strategy. On a 429, wait for the interval indicated by Retry-After (or until RateLimit-Reset) before retrying, and apply exponential backoff with jitter for repeated throttling. Proactively throttle client-side using RateLimit-Limit / RateLimit-Reset to avoid hitting the ceiling.

9. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks contain PII (names, addresses, dates of birth, driver license numbers) and financial data (prices, lien amounts, fees). Handling expectations:

• Transmit only over TLS; never log full payloads containing PII or credentials.
• Restrict storage of transaction data to what you need for correlation and reconciliation, and protect it at rest.
• Verify callback authenticity (HMAC) before persisting or acting on callback data.
• Serve callback endpoints over HTTPS.

This is guidance, not legal advice.

10. Support & Resources

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