Florida (FL) Title & Registration - Developer Guide

1. Overview & Introduction

The Florida (FL) Title & Registration API lets you submit and process vehicle title and registration transactions with the Florida Department of Motor Vehicles (DMV) and retrieve the resulting status, fees, and produced documents. It targets dealers and service providers that need to file electronic vehicle registration (EVR) work programmatically instead of through a manual portal.

The core domain object is the transaction: a submission that captures the vehicle, owner(s), lienholder, insurance, and registration intent, and is then processed asynchronously against the state. A transaction is identified two ways — by a numeric transaction ID and by a client-visible reference number (a UUID). Supporting resources hang off a transaction: forms (the documents a transaction produces), fees (the amounts a transaction calculates), and asynchronous callbacks (status notifications delivered to a URL you supply). Separately, the API offers state lookup operations (customer, ownership, and vehicle) that query the state directly and are used to gather and validate data before you build a transaction.

A transaction is scoped to a dealer location (locationId), an identifier Vitu issues to you that represents a specific dealer location. Many lookup operations require it. State lookups frequently chain: a VIN-based vehicle or ownership lookup can return a stateTransactionId that later lookups (by plate or title number) require.

Environments follow a single conceptual base URL with a swappable environment segment: a production environment plus staging and test environments. See the servers block in the spec for exact URLs; do not hardcode a specific host beyond the environment variable. Because transactions carry regulated personal data (driver license numbers, SSN/FEIN, dates of birth, addresses), treat all request and response payloads 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

• OAuth 2.0 client-credentials credentials issued by Vitu. Obtain these from the Key Management area in Vitu's Developer Portal.
• A dealer locationId, provided by Vitu.
• Familiarity with REST and OAuth 2.0 client-credentials.

Shortest path to a successful call

A read-only state lookup is the lowest-risk first call because it has no side effects.

1. Obtain a token from the OAuth token endpoint using your client credentials, requesting the API access scope (see the keycloak security scheme in the spec).
2. Attach the token as a bearer token on your request.
3. Call the vehicle lookup operation (GetVehicleLookup) with your locationId, a state, and a VIN-based search.
4. Read the response — a vehicle inquiry result. If it returns a stateTransactionId, retain it for follow-on lookups.

Once lookups succeed, move on to creating a transaction (CreateTransaction), which is asynchronous — see Common Use Cases.

# Conceptual sequence - see the spec for exact request/response shapes
1. POST {token endpoint}         -> access_token
2. POST /vehicle/lookup          (Authorization: Bearer <token>)
   - - -> vehicle record(s) [+ stateTransactionId]

3. Authentication & Access Walkthrough

The API defines a single security scheme: OAuth 2.0 client-credentials (named keycloak in the spec), requiring the oneapi:access scope. There are no alternative schemes (no API keys, no basic auth); every operation requires this token.

Obtaining credentials

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

Obtaining and attaching a token

1. Request an access token from the OAuth token endpoint (defined in the security scheme) using the client-credentials grant and the oneapi:access scope.
2. Send the token as a bearer token on every API request.

Token lifecycle

• Tokens are JWTs and expire. Cache a token and reuse it until shortly before expiry, then request a new one.
• On a 401 response, obtain a fresh token and retry once before treating it as a hard failure.
• Distinguish 401 (authentication — bad/expired token) from 403 (authenticated but not permitted for this API/resource). A 403 should not be retried with a new token; it indicates a permissions problem.

Acting on behalf of a user

Operations accept an optional x-on-behalf-of-user header to attribute a request to a specific user. Supply it when your integration acts for distinct end users; see the spec for the exact header definition.

4. Key Concepts & Glossary

How resources relate

• A transaction is the parent; forms and fees are derived children that exist only after processing has produced them.
• Lookups are independent of transactions but feed the data used to create one. A VIN lookup may yield a stateTransactionId that unlocks plate/title-number lookups.
• A reference number and numeric transaction ID are two keys to the same transaction.

5. Common Use Cases & Integration Patterns

5.1 Pre-fill and validate data via state lookups

Goal: gather authoritative vehicle/owner data before filing.

1. GetVehicleLookup by VIN — retrieve vehicle record and any stateTransactionId.
2. If searching by plate or title number, reuse the stateTransactionId from step 1.
3. GetCustomerLookup and/or GetOwnershipLookup — retrieve customer/ownership details, supplying stateTransactionId/stateCustomerId where the state requires them.

These operations are safe (read-only) and can be repeated freely.

5.2 Create and track a transaction (async)

Goal: submit a title/registration transaction and learn its outcome.

1. CreateTransaction with an FLEVRTransactionDTO body. Optionally supply a callbackUrl and transactionType. The response is an acceptance (202), not a final result — processing is asynchronous.
2. Learn the outcome by one of:

• Callback (preferred): if you supplied a callbackUrl, the platform POSTs a CallbackDTO on status change. Correlate it using refNumber.
• Polling: if you did not supply a callback, resolve refNumber → transaction ID via GetTransactionIdByRefNumber if needed, then poll derived resources (fees/forms) and status.

1. Once complete, retrieve fees (GetTransactionFees) and forms (GetTransactionForms), then download documents.

5.3 Amend or cancel a transaction

• Update: UpdateTransaction with the transaction identifier and a revised body. Also asynchronous (202).
• Cancel: CancelTransaction with the transaction identifier and an optional message. Asynchronous (202).

5.4 Retrieve produced documents

1. GetTransactionForms — enumerate available documents (FormDocumentDTO), including whether each is required/selected/signed.
2. Download either the full bundle (DownloadTransactionForms, optionally filtered by target) or a single document (DownloadTransactionDocument by documentId, optionally as a blank form).

Pattern guidance

• Prefer callbacks over polling. Supply a callbackUrl at create time so you are notified on status change rather than polling. Fall back to polling only when a callback endpoint is unavailable.
• Correlate by refNumber. It is the stable key you control from creation through callback delivery.
• Fees/forms exist only after processing. Do not fetch them immediately after a 202; wait for a completion signal.

6. Behavioral & Operational Notes

• Asynchronous processing. CreateTransaction, UpdateTransaction, and CancelTransaction return 202 Accepted — acknowledgment of receipt, not completion. Do not treat 202 as success of the underlying DMV action; wait for a callback or a status change.
• Dual identifiers. Operations that take a transaction identifier accept either the numeric ID or the refNumber UUID. Choose one consistently; GetTransactionIdByRefNumber bridges the two.
• Eventual consistency of derived resources. Fees and forms are populated as processing advances. Expect empty or partial results before completion.
• Callback authentication. Callbacks may be HMAC-signed (HMAC/SHA-256, base64-encoded) when an HMAC key is configured. Verify the signature on receipt.
• Document responses are binary. Download operations return application/pdf; handle them as binary streams, not JSON.

7. Asynchronous / Callback Patterns

The transaction operations declare an onStatusChange callback that POSTs to the callbackUrl you provide at request time.

• Flow: you supply callbackUrl on create/update/cancel → the platform processes asynchronously → on status change it POSTs a CallbackDTO to your endpoint → your endpoint returns 200 to acknowledge.
• Payload variants: CallbackDTO is polymorphic, discriminated by callbackType (success, failure, and type-specific variants such as EVR/DMVDESK/invoiced). Branch on the discriminator; see the spec for each variant's fields.
• Correlation: match callbacks to your request using refNumber (and transactionId where present).
• Acknowledgment: return 200 promptly. Non-200 responses signal the platform your endpoint did not accept the callback.
• Security: verify the HMAC signature when configured (see Behavioral 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.

8. Environments & Sandbox Access

Three environments are exposed through the environment segment of the base URL: a production environment, a staging environment, and a test environment (see the servers block for exact values). Use test/staging for integration work; obtain credentials for each from the Key Management area of Vitu's Developer Portal. Behavior across environments is intended to match; the primary difference is that non-production environments do not file real state transactions.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit, RateLimit-Reset), and 429 responses include Retry-After. Read these headers rather than hardcoding limits; the spec is the source for header definitions and the numeric ceilings drift over time.

Strategy: track remaining budget from the limit headers, and on 429 wait for the interval indicated by Retry-After (or until RateLimit-Reset) before retrying, using exponential backoff with jitter.

10. Pagination Conventions

Not applicable. List-returning operations (forms, fees) return arrays without pagination, filtering, or sorting parameters in the spec. The document download operation supports a target filter, and single-document download supports a blank flag — both are per-operation, not cross-cutting conventions.

11. Error Handling & Troubleshooting

Errors are returned using the Errors schema (an array of Error items) for most failures; some responses use a simple code/message object. Handle by class, not by memorizing specific codes:

Backoff convention: exponential backoff with jitter for 429/5xx; cap total attempts and surface a terminal error once the cap is reached. Never blindly retry mutating operations on ambiguous failures without confirming current transaction state.

12. Data Sensitivity & Compliance Notes

Transaction payloads and lookup responses carry regulated personal data — including driver license numbers, SSN, FEIN, dates of birth, and residential/mailing addresses. Handle accordingly:

• Transmit only over TLS (enforced by the HTTPS base URLs).
• Minimize retention; store only what your workflow requires, and protect at rest.
• Restrict access to callback-receiver endpoints and verify callback signatures before trusting payload contents.
• Treat downloaded PDFs as sensitive documents.

This is handling guidance, not legal advice; confirm your specific compliance obligations (e.g., DPPA, state requirements) with your compliance function.

13. Support & Resources

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