Kentucky (KY) Title & Registration API - Developer Guide

1. Overview & Introduction

The Kentucky (KY) Title & Registration API submits and processes title and registration transactions with the Kentucky Department of Motor Vehicles (DMV) and returns transaction status and confirmation data. It is one of Vitu's Electronic Vehicle Registration (EVR) interfaces, intended for dealers and their software providers who need to originate DMV title/registration work programmatically rather than through a manual portal.

The core noun is the transaction — a single title and/or registration submission for one vehicle. A transaction bundles everything the DMV needs to evaluate the work: the vehicle, one or more parties (owner, co-owner, lessor/lessee, lienholder, prior owner), insurance, prior-title information, and the registration action being requested. Each transaction carries a client-supplied reference identifier (refNumber, a UUID) and, once accepted into the Vitu system, a Vitu-assigned numeric transaction identifier. Both forms of identifier are accepted where an existing transaction must be addressed.

Processing is asynchronous. Submitting or updating a transaction returns an acceptance acknowledgement, not a final result. The authoritative outcome — DMV status, audit messages, assigned plate, shipment/indicia details, invoiced fees — is delivered through a callback to a URL you supply. Callbacks are typed (success, failure, EVR, DMVDESK, invoiced), and you correlate each callback to your original request via refNumber.

Environments follow a single server template with an environment variable: api (production), api-stage, and api-test. The environment forms part of the host; see the spec's servers block for the exact template. Credentials are environment-specific and issued by Vitu.

Sensitive-data note: transaction payloads contain personally identifiable information (owner/lessee names, dates of birth, driver license numbers, addresses, contact details) and vehicle/financial data. Treat all request and callback payloads as regulated PII. 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

• Familiarity with REST and OAuth 2.0 client-credentials.
• A set of Vitu-issued client credentials for the target environment. Obtain these from the Key Management area within Vitu's Developer Portal.
• A network-accessible HTTPS endpoint to receive callbacks, if you want asynchronous results delivered (recommended — see Async Patterns).

Shortest path to one successful submission

1. Obtain an access token using the client-credentials grant against the token endpoint defined by the keycloak security scheme, requesting the oneapi:access scope.
2. Build a transaction payload conforming to the KYEVRTransactionDTO schema. Include a client-generated refNumber (UUID) so you can correlate results.
3. Call the transaction-creation operation (CreateTransaction), attaching the bearer token. Optionally supply your callbackUrl and set the transaction type as appropriate for KY EVR work.
4. Receive the acceptance acknowledgement. This confirms the request was accepted for asynchronous processing — it is not the final outcome.
5. Wait for the callback at your callbackUrl, or otherwise coordinate with Vitu on result retrieval. Match the callback to your submission via refNumber.

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

3. Authentication & Access Walkthrough

Authentication uses OAuth 2.0 client credentials. The formal definition — grant type, token URL, and scope — lives in the spec under the keycloak security scheme; that is the single source of truth.

Obtaining credentials. Client credentials are issued by Vitu and are managed in the Key Management area of Vitu's Developer Portal. Credentials are environment-specific.

Obtaining a token. Exchange your client credentials at the token endpoint defined by the keycloak scheme, requesting the oneapi:access scope. You receive a bearer access token.

Attaching the token. Send the token as a bearer credential on every API call. All operations require the oneapi:access scope.

Token lifecycle. Access tokens expire. Cache and reuse a token until shortly before expiry, then request a new one. On a 401, discard the cached token, obtain a fresh one, and retry once; if it recurs, treat it as a credential/configuration problem rather than retrying in a loop. On a 403, the caller authenticated but lacks permission — do not retry; verify scope and entitlement.

Single scheme only. Only one security scheme (keycloak, client-credentials) is defined. There is no API-key or authorization-code alternative — do not build for one.

4. Key Concepts & Glossary

Relationships & lifecycle. A transaction is created, may be updated while still in progress, and moves through DMV processing asynchronously. Status is expressed through several enums depending on context (TransactionStatusEnum, UniversalStatusEnum, and callback-specific status fields). Consult the spec for the authoritative status value sets.

5. Common Use Cases & Integration Patterns

5.1 Submit a new title/registration transaction

1. Obtain a token (§3).
2. Assemble a KYEVRTransactionDTO with a client-generated refNumber, the vehicle, applicable parties, insurance, prior-title, and the registration action.
3. Call CreateTransaction, supplying your callbackUrl and the appropriate transaction type.
4. Persist the refNumber (and the returned identifier if provided) against your local record.
5. Wait for the callback to report the outcome; branch on callbackType.

Intent: originate DMV work and receive its result asynchronously.

5.2 Correct or complete an in-progress transaction

1. Identify the transaction by transactionId or refNumber.
2. Call UpdateTransaction with the revised payload.
3. Await a fresh callback reflecting the updated processing state.

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

5.3 Draft / save-for-later flow

The payload supports a saveForLater flag. Use it to create a transaction that is staged rather than fully submitted, then finalize later via UpdateTransaction.

Intent: stage work before committing it to DMV processing.

5.4 Handling outcome callbacks

Callbacks are typed via the callbackType discriminator:

• Success — processing completed; carries status, audit messages, shipment/indicia, assigned identifiers.
• Failure — processing failed; carries errors for diagnosis and remediation (often via §5.2).
• EVR / DMVDESK — channel-specific status, including assigned plate and deal status.
• Invoiced — fee/billing detail for the transaction(s).

Always correlate on refNumber, dispatch on callbackType, and treat unknown types defensively.

Sync vs. async. All meaningful results arrive asynchronously via callback. Do not treat the synchronous acceptance response as an outcome.

6. Behavioral & Operational Notes

• Asynchronous acceptance. The success response to create/update signals accepted for processing, not completed. The real result comes via callback. Design for this or you will misreport outcomes.
• Correlation is your responsibility. Supply and store a refNumber; it is the key that ties callbacks back to your submission.
• Update semantics. UpdateTransaction addresses an existing transaction by either identifier form. The spec does not state whether the update is a full replace or a partial merge of the KYEVRTransactionDTO. Flag: confirm replace-vs-merge behavior with Vitu before relying on partial updates; until confirmed, send a complete payload.
• Idempotency. No idempotency key mechanism is defined. Retrying CreateTransaction may create duplicate transactions. Guard against duplicate submission on your side (e.g. by not re-issuing a create for an already-accepted refNumber).
• Callback security. The spec notes that when an HMAC key is configured for callbacks, the payload is signed using HMAC/SHA-256 (base-encoded). If you configure signing, verify the signature on receipt. Coordinate key setup with Vitu.
• Callback acknowledgement. Your callback endpoint is expected to return a success acknowledgement to indicate acceptance. Delivery/retry behavior for un-acknowledged callbacks is not specified — see §9.
• On-behalf-of header. An optional header lets a request act on behalf of a specific user. Use only if Vitu has provisioned this for your integration; otherwise omit.

7. Asynchronous / Callback Patterns

Conceptual flow. You submit (or update) a transaction and provide a callbackUrl. The transaction is processed asynchronously. When status changes or a result is available, Vitu POSTs a typed CallbackDTO to your URL. Your endpoint validates and acknowledges it.

Correlation. Match each callback to its originating request using refNumber (present on the callback base). Dispatch handling on callbackType.

Signing. If an HMAC key is configured, callbacks are signed with HMAC/SHA-256. Verify before trusting payload contents.

​> 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 available via the server template's environment variable: api (production), api-stage, and api-test. Use api-test for initial integration and api-stage for pre-production validation. Credentials are issued per environment through the Developer Portal's Key Management area; a token obtained for one environment is not valid for another.

See §3's flag regarding the auth (token) endpoint host, which does not appear to be environment-templated the way the API host is — confirm the correct token endpoint per environment with Vitu.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit, RateLimit-Reset) and, on throttling, a Retry-After header. Read these headers rather than hardcoding values; the numeric limits are not fixed in this guide and live in the spec/runtime headers. On a throttled response, wait for the period indicated by Retry-After (or until RateLimit-Reset) before retrying, and apply backoff for repeated throttling. See §11 for the retry classification.

10. Error Handling & Troubleshooting

Handle errors by class, not by memorizing individual codes (which drift). Error payloads for request failures use the Errors schema; some auth/throttle responses use a simpler code/message object. Consult the spec for exact shapes.

Backoff convention. For retryable classes, use exponential backoff with jitter, respecting Retry-After when present, and cap total attempts. Never retry validation or forbidden failures without changing the request.

Note: processing failures (as opposed to submission errors) are reported asynchronously via failure-type callbacks, not synchronous error responses. Diagnose those from the callback's errors content.

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks carry PII (names, dates of birth, driver license numbers, addresses, contact details) and financial data (selling price, fees, trade-in values). Handling expectations:

• Transmit only over the provided HTTPS endpoints; never log full payloads containing PII/license numbers.
• Restrict access to stored refNumber↔PII mappings.
• Secure your callback endpoint (HTTPS, signature verification where HMAC is configured).
• Retain data only as long as your DMV/business obligations require.

This is handling guidance, not legal advice.

12. Support & Resources

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