Idaho (ID) Title & Registration - Developer Guide

1. Overview & Introduction

The Idaho (ID) Title & Registration API lets you submit vehicle title and registration transactions to the Idaho Department of Motor Vehicles (DMV) through Vitu, and receive back processing status and confirmation data. It is the electronic vehicle registration (EVR) integration point for dealers and their software providers who need to file title/registration work programmatically instead of through manual DMV channels.

The central domain object is the transaction. A transaction bundles everything the DMV needs to evaluate one title/registration filing: the vehicle, the owner(s) and any co-owner, optional lessee/lessor and lienholder parties, trade-ins, and the registration action being requested. The transaction request body is defined by the IDEVRTransactionDTO schema. The nature of the filing is expressed through two related concepts: the transactionType (an operational routing dimension — see TransactionTypeEnum) and the applicationType inside the transaction body (the DMV work being requested, e.g. title-and-registration vs. title-only).

Processing is asynchronous. When you submit a transaction, the API accepts it for background processing rather than returning a finished result inline. Final outcomes — success, failure, DMV desk status, EVR results, or invoicing — are delivered through callbacks to a URL you supply, described by the CallbackDTO family. A transaction is identified for later reference by both a server-assigned numeric transactionId and a client-visible UUID refNumber.

The API is served from a single environment-parameterized base URL with three deployment targets (api for production, api-stage, and api-test); see the servers block in the spec for the exact host template. All access is via OAuth 2.0 client credentials.

Sensitive data: transaction bodies carry personally identifiable and regulated information (SSN, FEIN, driver license numbers, dates of birth, owner/lessee addresses). Treat all request and callback 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

• A Vitu-issued OAuth 2.0 client credential (client ID and secret).
• The ability to reach the environment host for your target (api-test is the right starting point).
• If you want to receive results, a network-accessible HTTPS endpoint to act as your callback receiver.

Obtain access

Credentials are issued by Vitu and are available from the Key Management area within Vitu's Developer Portal. Use those credentials with the client-credentials flow described in the spec's keycloak security scheme.

Minimal happy path

1. Get a token. Exchange your client credentials for an access token at the token endpoint defined in the keycloak security scheme, requesting the oneapi:access scope.
2. Submit a transaction. Call the CreateTransaction operation with an IDEVRTransactionDTO body. Provide your callback URL and, if relevant, the transactionType. This operation returns an acceptance response — it does not return the final result.
3. Receive the outcome. Your callback endpoint receives a CallbackDTO when processing reaches a terminal or notable state. Correlate it back to your submission using refNumber.
4. (Optional) Amend. If you need to change an in-flight or draft transaction, call UpdateTransaction with the transaction's identifier.

Note — request body detail: The IDEVRTransactionDTO schema is large and mostly optional at the schema level. The spec does not encode which fields are conditionally required for a given applicationType or registration.action.

3. Authentication & Access Walkthrough

The API defines a single security scheme, keycloak, using the OAuth 2.0 client-credentials flow with the scope oneapi:access. The formal definition (token URL, refresh URL, scope name) lives in the spec's securitySchemes — refer to it there rather than to any copy.

There is only one authentication mechanism. If your integration assumes API keys or an authorization-code/user-login flow, that expectation does not apply here — this is a machine-to-machine flow.

Obtaining and using tokens

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 in the keycloak scheme, requesting the oneapi:access scope.
3. Attach the returned bearer token to each API request as an Authorization: Bearer <token> header.

Token lifecycle

• Access tokens expire. Cache and reuse a token until shortly before its expiry, then request a fresh one; do not request a new token per call.
• On a 401 response, obtain a fresh token and retry once. If the retry still fails with 401, treat it as a credential/configuration problem, not a transient error.
• A 403 means the caller authenticated successfully but lacks permission — do not retry; escalate to obtain the correct access.

Environment differences

The env server variable selects the deployment.

4. Key Concepts & Glossary

How resources relate

There is effectively one addressable resource — the transaction — with all parties and the vehicle embedded within it. There are no separately created child resources to link; you assemble the full picture in a single IDEVRTransactionDTO.

Lifecycle and callback types

A transaction moves through states over its lifetime. The CallbackDTO discriminator (callbackType) selects which callback shape you receive:

• SUCCESS — terminal success detail, including status, any audit messages, and shipment/indicia info.
• FAILURE — processing failed; carries error detail.
• EVR — EVR-specific result (e.g. assigned plate, control number).
• DMVDESK — DMV-desk deal status detail, including bundle errors flagged as fixable/fixed.
• INVOICED — invoicing detail for one or more transactions and their fees.

The exact status vocabularies (TransactionStatusEnum, UniversalStatusEnum, EDealStatus) and each callback subtype's fields are defined in the spec; consult it for authoritative values.

5. Common Use Cases & Integration Patterns

Each scenario references operations by name. Ordering and correlation are the parts the spec cannot express.

Scenario A - Submit a new title/registration filing

1. Acquire a token (client-credentials, oneapi:access).
2. Assemble the transaction body (IDEVRTransactionDTO): vehicle, owner(s), registration action, and the appropriate applicationType/serviceType.
3. Call CreateTransaction, supplying your callbackUrl and, where applicable, transactionType.
4. Store the refNumber you sent (and the returned identifiers if present) so you can correlate callbacks.
5. Wait for a callback. Branch on callbackType: handle SUCCESS/EVR/INVOICED as progress or completion, and FAILURE as needing correction.

Scenario B - Amend an in-flight or draft transaction

1. Acquire a token.
2. Call UpdateTransaction with the transaction's identifier (numeric transactionId or UUID refNumber — the path parameter accepts either) and the revised body.
3. Await the resulting callback as in Scenario A.

Use UpdateTransaction for corrections and for progressing a saved draft (saveForLater).

Scenario C - Correct a rejected filing

1. Receive a FAILURE (or a DMVDESK callback carrying bundleErrors).
2. Inspect the error/bundle-error detail. For DMV-desk bundle errors, the fixable flag indicates whether the issue can be resolved and re-submitted.
3. Call UpdateTransaction with corrections.
4. Await the next callback.

Recommended patterns

• Async-first, callback-driven. These operations return acceptance, not results. Design around receiving callbacks; do not block waiting on the initial response for outcome data.
• Idempotency via refNumber. Generate and retain a stable refNumber per logical filing so you can correlate and de-duplicate. (See the operational note on retry semantics.)
• Secure your callback receiver. Callbacks may be signed (see Asynchronous / Callback Patterns); verify signatures and require HTTPS.

6. Behavioral & Operational Notes

• Acceptance ≠ completion. A successful response to CreateTransaction/UpdateTransaction means the request was accepted for asynchronous processing. The true outcome arrives only via callback. Never treat the initial response as confirmation of a filed transaction.
• Correlate on refNumber. Callbacks carry refNumber; some subtypes also carry transactionId. refNumber is the reliable correlation key because you control it and can set it before submission.
• Identifier flexibility on update. The UpdateTransaction path identifier accepts either the numeric transactionId or the UUID refNumber. Choose one consistently within your integration.
• saveForLater drafts. The body includes a saveForLater flag; a saved transaction is a draft rather than a submitted filing.

7. Asynchronous / Callback Patterns

The API delivers results through the onStatusChange callback declared on the transaction operations. You supply callbackUrl at submission time; Vitu POSTs a CallbackDTO to it when status changes.

Flow:

1. Submit with a callbackUrl that is HTTPS and network-reachable from Vitu.
2. Your endpoint receives a CallbackDTO; dispatch on callbackType (SUCCESS, FAILURE, EVR, DMVDESK, INVOICED).
3. Correlate to your original submission via refNumber.
4. Respond with a success status (per the callback's declared responses) to acknowledge receipt.

Signing: The spec indicates that when an HMAC key is configured, callbacks are signed using HMAC/SHA-256 (base64-encoded). Verify this signature before trusting a payload.

​> 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 deployment targets are exposed via the env server variable: production (api), staging (api-stage), and test (api-test). Begin integration against api-test. Credentials are environment-specific and issued from the Key Management area of Vitu's Developer Portal. Refer to the spec's servers block for the exact host template.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (RateLimit-Limit, RateLimit-Reset), and 429 responses include Retry-After. Read these headers by name rather than hard-coding limits; the numeric values are governed by the server and may change.

Convention: On 429, wait for the interval indicated by Retry-After before retrying. If absent, use exponential backoff with jitter. Proactively slow down as RateLimit-Limit/RateLimit-Reset indicate you are approaching the window boundary.

10. Error Handling & Troubleshooting

Handle failures by class, not by individual code. The Errors schema (an array of Error) is the primary error body for validation, not-found, and server responses; auth and rate-limit responses use a code/message object. Refer to the spec for exact shapes and status codes.

Backoff convention: exponential with jitter, a sane maximum attempt count, and a stop condition once errors are clearly non-transient (auth-forbidden, validation, not-found).

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks contain regulated personal data — SSN, FEIN, driver license numbers, dates of birth, and residential/mailing addresses for owners, co-owners, and lessees.

• Transmit only over TLS; the API and callback receiver must both use HTTPS.
• Minimize retention of raw PII; store only what your workflow requires.
• Restrict access to submitted payloads and received callbacks.
• Verify callback authenticity (HMAC signature) before processing.

This is handling guidance, not legal advice.

12. Support & Resources

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