Texas (TX) Title & Registration - Developer Guide

1. Overview & Introduction

The Texas (TX) Title & Registration API submits and processes vehicle title and registration transactions with the Texas Department of Motor Vehicles (DMV) and returns transaction status and confirmation data. It lets you integrate electronic vehicle registration (EVR) workflows directly into your own dealer, lender, or service-provider software instead of processing transactions manually.

The core domain object is the transaction — a single title and/or registration submission for one vehicle. A transaction carries the parties involved (owner, co-owner, lessees, lienholder, seller), the vehicle being titled/registered, any trade-in vehicles, prior title information, and service and registration options. The exact composition is defined by the TXEVRTransactionDTO schema in the spec. Each transaction is identified by a system-assigned integer transaction ID and by a caller-supplied UUID reference number (refNumber); either can be used to address an existing transaction.

Processing is asynchronous. When you submit or update a transaction, the API acknowledges receipt and continues processing in the background. Outcomes (success, failure, EVR/DMVDESK-specific results, invoicing) are delivered later via a callback to a URL you supply, modeled by the CallbackDTO family in the spec.

The API is served across three conceptual environments — production, staging, and test — selected via the env server variable defined in the spec's servers block. Access is gated by OAuth 2.0 client credentials (the keycloak security scheme). Because transactions contain regulated personal and vehicle data (driver license numbers, FEINs, addresses, VINs), treat all request and callback payloads as sensitive; see Data Sensitivity.

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

• Client credentials issued by Vitu (see below).
• Familiarity with REST and OAuth 2.0 client-credentials.
• A network-accessible HTTPS endpoint to receive callbacks, if you want asynchronous results delivered (the callback URL must be reachable by Vitu's servers).

Obtain access

Credentials (client ID and secret) are obtained from the Key Management area within Vitu's Developer Portal. These credentials are used with the keycloak OAuth 2.0 client-credentials flow defined in the spec.

Minimal happy path

1. Get a token. Exchange your client credentials for an access token using the client-credentials flow, requesting the scope defined in the spec (oneapi:access). See Authentication.
2. Submit a transaction. Call the create-transaction operation (CreateTransaction) with a TXEVRTransactionDTO body. Optionally supply a callback URL and a transaction type. The API responds with an asynchronous-acceptance response — this confirms receipt, not completion.
3. Receive the outcome. When processing finishes, Vitu POSTs a CallbackDTO to your callback URL. Correlate it to your submission using the refNumber you supplied. See Asynchronous & Callback Patterns.

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

3. Authentication & Access Walkthrough

The formal security definition is the keycloak scheme in the spec (type: oauth2, clientCredentials flow, scope oneapi:access). This section covers only the operational how-to the scheme cannot express.

Only one authentication scheme exists. There is no API-key or user-password alternative; all calls use the OAuth 2.0 client-credentials flow. If you expect interactive/user-context calls, note that user context is instead passed via the optional x-on-behalf-of-user header (see the spec) — not via a different auth flow.

Obtaining and using a token

1. Retrieve your client ID and secret from the Key Management area of Vitu's Developer Portal.
2. Request an access token from the token endpoint using the client-credentials grant and the oneapi:access scope.
3. Attach the returned bearer token to each API request per standard OAuth 2.0 bearer usage.

Token lifecycle

• Access tokens are short-lived (JWTs). Cache and reuse a token until it nears expiry rather than requesting one per call.
• On a token expiry / auth failure (the spec's 401 response class), obtain a fresh token and retry the request once. Do not retry indefinitely.
• A 403 response class means the caller is authenticated but lacks permission — this is not retryable; re-check scope grants and entitlements rather than retrying.

Environment differences

Select the environment via the env server variable in the spec. Credentials and reachable token endpoints differ per environment.

4. Key Concepts & Glossary

Resource relationships & lifecycle

• A transaction is created once and can be updated while still open/editable. There is no delete operation in the spec.
• Callbacks are downstream of a transaction: a single transaction may produce more than one callback over its lifecycle (e.g. an EVR result, then an invoiced summary).
• refNumber is the durable correlation key you control end-to-end; the integer transaction ID is assigned by the system.

5. Common Use Cases & Integration Patterns

Operations are referenced by name; see the spec for request/response detail.

Submit a new title & registration transaction

1. Obtain a token.
2. Call CreateTransaction with a TXEVRTransactionDTO, supplying your own refNumber, a callback URL, and (optionally) a transaction type.
3. Receive the asynchronous-acceptance response.
4. Await the callback POST; branch on callbackType (SUCCESS/EVR vs FAILURE).

Correct or complete a pending transaction

1. Address the existing transaction via UpdateTransaction using either the integer transaction ID or the refNumber.
2. Submit the revised TXEVRTransactionDTO.
3. Await a fresh callback for the updated outcome.

Whether a transaction remains updatable depends on its processing state. A 404 class response means the target could not be found (wrong identifier, or not yet persisted). See Behavioral Notes.

Save a draft for later

Set the transaction's saveForLater flag when creating/updating so the transaction is retained without full submission. Complete it later via UpdateTransaction.

Reconcile fees / invoicing

When invoicing completes, expect an INVOICED callback variant carrying per-transaction fee detail (InvoicedTransactionDTO / InvoicedTransactionFeeDTO). Use it to reconcile charges against your records, keyed by refNumber / transaction ID.

Recommended pattern: callbacks over polling

This API is callback-driven; there is no read/status operation in the spec. Supply a callback URL and treat the callback as the sole authoritative result channel. Do not build a polling loop — there is no operation to poll.

6. Behavioral & Operational Notes

• Acceptance ≠ completion. The synchronous response to create/update signals accepted for asynchronous processing only. Success or failure is determined solely by the later callback. Do not treat the acceptance response as a completed transaction.
• Callback is the success signal. Determine outcome from the callback's callbackType discriminator and its payload, not from the initial HTTP status.
• Update semantics. UpdateTransaction replaces the transaction with the submitted body. Because the body is a full TXEVRTransactionDTO, send the complete intended state rather than a partial patch.
• Dual identifiers. UpdateTransaction accepts either the integer transaction ID or the UUID refNumber in the same path position. Choose one consistently; refNumber is recommended since you control it from creation.
• Callback authenticity. If an HMAC key is configured for callbacks, verify the HMAC/SHA-256 signature before trusting a callback payload.
• Conditional required fields. The schema marks most party/vehicle fields as nullable/optional, but actual DMV requirements depend on transaction type, ownership, and lease structure. Structural validity per the schema does not guarantee acceptance; expect 400/FAILURE results for business-rule violations the schema cannot express.

7. Asynchronous / Callback Patterns

The create and update operations declare an onStatusChange callback in the spec: when processing state changes, Vitu POSTs a CallbackDTO to the callbackUrl you provided.

• Delivery target. The callback URL you pass must be HTTPS and reachable from Vitu's servers.
• Correlation. Match callbacks to submissions using refNumber (and/or the transaction ID present in most variants).
• Variant dispatch. Branch on the callbackType discriminator to select the correct payload shape (SUCCESS, FAILURE, DMVDESK, EVR, INVOICED).
• Your response. Return the success status the spec's callback definition expects to acknowledge receipt; return an error status to signal you did not accept it.
• Signature verification. When an HMAC key is configured, validate the HMAC/SHA-256 signature.

​> 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 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 differ per environment — obtain and confirm them via the Key Management area of Vitu's Developer Portal.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit, RateLimit-Reset) and, on throttling, a Retry-After header, as defined per-response in the spec. Read these headers rather than hardcoding limits.

• On a rate-limit response class (429), pause for the duration indicated by Retry-After, then retry.
• Use RateLimit-Reset to schedule when to resume if you approach the limit proactively.
• Apply exponential backoff with jitter for repeated throttling.

The spec does not publish specific numeric limits; the header values at runtime are authoritative.

10. Error Handling & Troubleshooting

Error bodies use the spec's Errors/Error schema (or a code/message object for some auth/throttle responses). Handle by class, not by memorizing codes:

Refer to the spec's Errors schema for the exact error body structure.

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks include regulated personal and vehicle data — driver license numbers and types, FEINs, names, contact details, residence addresses, and VINs. Handling expectations:

• Transmit only over TLS (enforced by the HTTPS-only server and callback URL constraints).
• Store the minimum necessary; avoid logging full payloads, especially license numbers and FEINs.
• Ensure callback-receiving endpoints are access-controlled and verify HMAC signatures when configured.

This is guidance, not legal advice.

12. Support & Resources

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