Oregon (OR) Title & Registration - Developer Guide

1. Overview & Introduction

The Oregon (OR) Title & Registration API submits and processes vehicle title and registration transactions with the Oregon Department of Motor Vehicles (DMV) through Vitu, returning transaction status and confirmation data. It exists so that dealer-facing and back-office systems can originate DMV work electronically instead of via manual or paper-based filing, and receive structured status and audit information as the transaction moves through processing.

The central domain object is the transaction. A transaction represents a single DMV filing and carries the vehicle, owner(s), lienholder, insurance, prior-title, registration, and seller details required to process it. A transaction is created, then optionally updated, and is processed asynchronously by Vitu and the DMV — the API acknowledges receipt immediately and reports the real outcome later. Each transaction has a transaction type (the spec's TransactionTypeEnum) and an application type (title-and-registration, title-only, and related variants — see the request DTO in the spec) that together determine what DMV work is performed.

Transactions are identified two ways: a Vitu-assigned numeric identifier and a client-supplied/returned reference number (UUID). Both are accepted where a transaction identifier is required, and the reference number is the value echoed back in asynchronous callbacks — making it the durable correlation key between your request and later status events.

The API is served from a single base host with a selectable environment segment (production plus staging and test variants); the exact server template and environment values live in the spec's servers block. All access is via OAuth 2.0 client credentials.

Sensitive data up front: Transaction payloads contain personally identifiable information (owner and co-owner names, dates of birth, driver license numbers, addresses, phone, email) and lienholder/financial identifiers. Treat all request and callback payloads as regulated PII in transit and at rest. 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 accept inbound HTTPS callbacks if you want asynchronous status (recommended — see Asynchronous / callback patterns).
• Familiarity with REST and OAuth 2.0 client-credentials.

Obtain access

Credentials are issued by Vitu and can be obtained from the Key Management area within Vitu's Developer Portal. Use the credential to request an access token from the token endpoint defined in the spec's security scheme, requesting the scope defined there.

Minimal happy path

1. Get a token. Exchange your client credentials for an access token (client-credentials grant).
2. Create a transaction. Call the transaction-creation operation (CreateTransaction) with an OR EVR transaction payload (the request DTO in the spec). Optionally supply a callback URL so status is pushed to you.
3. Receive acknowledgement. The operation acknowledges asynchronously — it confirms the request was accepted for processing, not that DMV work is complete. Persist the returned reference number.
4. Learn the outcome. Wait for the asynchronous callback(s) carrying the real result, correlated by reference number. (There is no read/status operation in this spec — see the note in Key concepts.)

# 1. Token (shape per the spec's security scheme; values illustrative)
curl -X POST "<token endpoint from spec>" \
  -d grant_type=client_credentials \
  -d client_id=... -d client_secret=... \
  -d scope="<scope from spec>"

# 2. Create transaction (attach the token; body per the request DTO in the spec)
curl -X POST "https://<env-host-from-spec>/.../transaction?callbackUrl=https://you.example/hook" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d @transaction.json

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

3. Authentication & Access Walkthrough

Authentication uses OAuth 2.0 client credentials. The formal definition — flow type, token endpoint, and scope — is the security scheme in the spec (named keycloak there; the client-facing scheme name is oneVituOauth). Do not treat the values below as the definition; the spec is authoritative.

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

Obtaining a token. Perform a client-credentials token request against the token endpoint in the spec, requesting the scope declared there. You receive a bearer access token.

Attaching the token. Send it as Authorization: Bearer <token> on every API call.

Token lifecycle. Access tokens expire. Cache a token and reuse it until shortly before expiry, then request a new one.

Auth-failure handling. On an authentication failure, re-authenticate and retry a single time. On an authorization failure (authenticated but not permitted), do not retry — the credential lacks access; contact Vitu.

Environment differences. The same credential model applies across the environments defined in the spec's servers block.

Only one scheme exists. This API supports client-credentials only. There is no API-key or authorization-code alternative.

4. Key Concepts & Glossary

Resource relationships & lifecycle. A transaction is the single top-level resource; owner, co-owner, lienholder, insurance, vehicle, registration, and previous-title are nested within its payload, not separate resources. Lifecycle: create → (optional update) → asynchronous processing → callback(s) reporting SUCCESS / FAILURE / type-specific / INVOICED states. State is authoritative only via callback status fields.

NOTE — no read operation. The spec exposes only create and update operations. There is no GET/status/list operation. Learning a transaction's outcome therefore depends entirely on receiving callbacks.

5. Common Use Cases & Integration Patterns

Scenario A - Submit a new OR title & registration filing

1. Authenticate (client-credentials token).
2. Create the transaction (CreateTransaction) with the appropriate transaction type and application type, supplying a callback URL. Intent: hand a complete filing to Vitu for asynchronous DMV processing.
3. Store the reference number returned/echoed. Intent: correlation key for callbacks.
4. Await callbacks. Intent: SUCCESS/type-specific callbacks carry confirmation data (control number, assigned plate, shipment tracking); FAILURE callbacks carry errors.

Scenario B - Correct or complete a submitted transaction

1. Update the transaction (UpdateTransaction) using the transaction ID or reference number. Intent: revise details (e.g. after a FAILURE callback, or to complete a draft).
2. Await new callbacks for the updated transaction.

Use update to iterate on a transaction that hasn't reached a terminal state. The spec doesn't define which states permit update — confirm terminal-state rules with Vitu.

Scenario C - Save-and-resume (draft) workflow

The request DTO includes a save-for-later indicator and Draft-style states appear in the status enums. Create with the save-for-later flag to persist a draft, then update later to progress it. Intent: stage incomplete filings without submitting them.

Recommended patterns

• Async, callback-driven. Every operation acknowledges immediately and processes asynchronously. Treat the HTTP acknowledgement as "accepted," never as "done."
• Callbacks over polling. No read operation exists; register a callback URL and drive your state machine from callback type + status fields.
• Correlate by reference number. Key your persistence on the UUID reference number, since it is present across callback variants.
• Idempotency on retries. See Behavioral notes before blindly retrying a create.

6. Behavioral & Operational Notes

• Acknowledgement ≠ completion. The create/update responses confirm acceptance for asynchronous processing. Real success or failure arrives only via callback status.
• Success is a state, not a status code. Judge outcome by the callback type and the status/universal-status fields, not by the HTTP response of the original call.
• Callback authenticity (HMAC). The spec indicates that when an HMAC key is configured, callbacks are signed using HMAC-SHA256 (base64-encoded). If you enable this, verify the signature on inbound callbacks before trusting them.
• Callback delivery target. Callbacks are POSTed to the callback URL you supply on the originating request; your endpoint should return a 2xx to acknowledge. Retry/delivery guarantees are not specified — see the note in Asynchronous patterns.
• On-behalf-of header. An optional header lets you act on behalf of another user (see the header parameter in the spec). Supplying it changes attribution of the transaction; omit it unless Vitu has provisioned this for you.

7. Asynchronous / Callback Patterns

Flow. You supply a callback URL when creating (or updating) a transaction. Vitu processes the transaction asynchronously and POSTs a callback to that URL as status changes.

Payloads. The callback body is discriminated by callback type (CallbackTypeEnum → the callback DTO variants: success, failure, EVR, DMV-desk, invoiced). Branch on the discriminator to parse the correct variant. See the callback schemas in the spec for fields.

Correlation. Match callbacks to your originating request by the reference number (UUID) present on the callback envelope.

Acknowledgement. Your endpoint should return a 2xx when it accepts a callback.

Security. When configured, callbacks are HMAC-SHA256 signed (base64). Verify before trusting.

​> 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 spec defines multiple environments via the server template's environment variable (a production environment plus staging and test variants). Use a non-production environment for integration and testing, and switch only the environment segment of the host to promote to production. Exact host values live in the spec's servers block.

9. Rate Limiting & Quotas

Responses carry rate-limit headers (a limit header and a reset header), and throttled requests return a "too many requests" condition with a retry-after header. Read these headers by name rather than assuming fixed numbers — the concrete limits are governed by the spec/response headers and may change.

Convention: On a throttling response, wait for the period indicated by the retry-after header before retrying; if absent, apply exponential backoff with jitter. Treat throttling as retryable.

10. Error Handling & Troubleshooting

Errors are returned using the spec's error structures (the Errors array of Error, and a simple code/message object for auth and throttling responses). Handle by class, not by specific code:

Backoff convention: exponential with jitter, capped attempts. Never retry validation or authorization failures without changing the request.

Failure of the transaction itself (as opposed to the HTTP call) is reported via a FAILURE callback carrying error details — handle it in your callback processing, not your HTTP error handling.

11. Data Sensitivity & Compliance Notes

Transaction payloads and callbacks contain PII: owner/co-owner names, dates of birth, driver license numbers, gender, contact details, and residential/mailing addresses, plus lienholder and financial identifiers. Handling expectations:

• Transmit only over TLS; never log full payloads containing PII or credentials.
• Restrict storage of DOB, driver license numbers, and addresses to what your integration requires, and protect it at rest.
• Verify HMAC signatures on callbacks (when enabled) before processing.
• Treat access tokens and client secrets as secrets; source them from secure storage, not code.

This is handling guidance, not legal advice. Confirm jurisdiction-specific DMV/PII compliance obligations with Vitu and your own compliance function.

12. Support & Resources

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