Montana (MT) NTX Salvage Title - Developer Guide

1. Overview & Introduction

The Montana (MT) NTX Salvage Title API lets external systems submit and manage Montana salvage title applications through Vitu's national public API platform. It removes the need to interact with the state directly: your integration assembles the transaction data, Vitu processes it, and the API returns generated forms, status updates, and produced documents.

The central noun is the transaction — a single salvage title application containing the vehicle, owner, seller, prior title, and salvage-brand information. A transaction moves through a lifecycle: it is created, optionally updated, and finally committed for processing (or cancelled). During and after processing, a transaction produces forms (generated documents tied to that transaction) and may accrue ticket messages (a comment/correspondence thread used to exchange information and supporting files with Vitu's processing team). Separately, you can upload your own supporting documents and associate them with a transaction.

Because processing is inherently asynchronous, most write operations acknowledge the request immediately and continue working in the background. The API surfaces outcomes through callbacks (webhooks) that you register per request. The callback payload is polymorphic — its shape depends on the type of event (success, failure, and other platform event types). This makes callbacks the primary mechanism for learning the true result of a submission.

The API is served from a single host template with a selectable environment segment. The spec defines three environments (production plus staging and test variants). Treat production as live and state-affecting; use the non-production environments for integration work. Refer to the servers block in the spec for the exact URL template and environment values.

Transactions carry personally identifiable owner information (names, addresses, and business identifiers such as FEIN). Treat all request and response payloads as sensitive and transmit them only over TLS.

2. Getting Started / First Call

Prerequisites

• A registered Vitu client credential (see Authentication).
• Your Vitu Location ID (a UUID). Document and ticket operations require it as a header.
• A publicly reachable HTTPS endpoint if you intend to receive callbacks.

Obtain access

Credentials are issued by Vitu and are available from the Key Management area within Vitu's Developer Portal. Use those credentials to obtain an OAuth 2.0 access token via the client-credentials flow (see the security schemes in the spec).

Minimal happy path

1. Obtain a token using your client credentials.
2. Create a transaction with CreateTransaction, supplying the salvage title data and (recommended) a callbackUrl. The response is an asynchronous acknowledgement, not a final result.
3. Wait for a callback at your registered URL, or retrieve produced documents once processing has advanced.
4. List produced forms with GetTransactionForms and download them with DownloadTransactionForms or DownloadTransactionDocument.
5. Commit the transaction with CommitTransaction when you are ready to finalize, supplying shipping and (where applicable) plate-destination and signer details.

The create/update operations accept the salvage transaction body defined by the NTXSalvageTransactionDTO schema. For Montana salvage titling, the state and applicationType fields are constrained to Montana salvage values — see the spec for the exact allowed values.

3. Authentication & Access Walkthrough

The spec defines the formal security under two OAuth 2.0 client-credentials schemes: auth0 and keycloak. Both are declared at the API level, meaning a token from either issuer is accepted. Consult the spec's securitySchemes for the authoritative token URLs and scope names (api_access for auth0, oneapi:access for keycloak).

Obtaining and using a token

1. Retrieve client credentials from the Key Management area in Vitu's Developer Portal.
2. Request an access token from your issuer's token endpoint using the client-credentials grant and the scope defined for that scheme.
3. Attach the resulting token as a Bearer credential on every API request.

Token lifecycle

• Tokens are short-lived JWTs; cache and reuse a token until shortly before expiry rather than requesting one per call.
• On a 401 response, obtain a fresh token and retry once. A repeated 401 indicates a credential or scope problem, not an expiry problem.
• A 403 means the token is valid but the caller lacks permission for the operation — do not retry; resolve entitlements with Vitu.

Two schemes, one choice: Although two issuers are listed, they are alternatives, not a required pair. Pick the issuer for which Vitu provisioned your credentials. If you were issued only one, use only that one.

Environment differences

Use the same credential flow across environments, but note that the token URLs in the spec point at Vitu-hosted issuers; align your token endpoint with the environment you are calling. Non-production environments do not produce state-filed results.

4. Key Concepts & Glossary

How resources relate

• A transaction is the parent of its forms, uploaded documents, and ticket messages.
• Documents are uploaded against a transaction ID and can then be linked into a ticket message.
• Forms exist only once a transaction has been created and processed far enough to generate them.
• Commit is a terminal-intent action on a transaction; cancel is the opposing terminal action.

Lifecycle states

The spec exposes several status enumerations (TransactionStatusEnum, UniversalStatusEnum, and callback-specific status types). Treat these as the source of truth for state values.

5. Common Use Cases & Integration Patterns

5.1 Submit a new salvage title application

1. CreateTransaction — supply the salvage transaction body and a callbackUrl. Intent: register the application and begin async processing.
2. Receive a callback (or poll produced forms) to learn the outcome.
3. GetTransactionForms → DownloadTransactionForms / DownloadTransactionDocument — obtain generated output.
4. CommitTransaction — finalize with shipping/plate/signer details once the application is ready.

5.2 Correct or extend an in-progress transaction

1. UpdateTransaction — resubmit the transaction body under the existing ID/reference number. Intent: revise data before commit.
2. Re-check forms and callbacks for the updated result.

5.3 Provide supporting documents

1. uploadDocument — upload one or more files against the transaction ID, tagging each with a DocumentTypeEnum value and supplying x-location-id. Intent: attach evidence the state or Vitu requires.
2. Optionally getDocument / getDocumentContent to verify what was stored; deleteDocument to remove an incorrect upload.

5.4 Correspond with Vitu processing

1. uploadDocument (if you need to attach files).
2. createTicketMessage — post a message on the transaction's thread, optionally linking the uploaded document IDs.
3. getTicketMessages — read the thread, including responses.

5.5 Cancel an application

• CancelTransaction — cancel the transaction, optionally including a message. Intent: withdraw before finalization.

Ordering, dependencies, and patterns

• Create before everything. Forms, documents, ticket messages, and commit all require an existing transaction.
• Prefer callbacks over polling. Register a callbackUrl on write operations; only poll GetTransactionForms as a fallback where a callback endpoint is not available.
• Commit last. Treat CommitTransaction as the final step after the data and any required documents are in place.
• Upload before linking. A ticket message can only reference document IDs that already exist from a prior upload.

6. Behavioral & Operational Notes

• Asynchronous acknowledgement. Create, update, commit, and cancel return an accepted-style acknowledgement rather than a completed result. The true outcome arrives via callback or becomes visible on subsequent reads. Do not treat the acknowledgement as success of the underlying titling operation.
• Success is a state, not a status code. Determine real success from the callback variant/status fields or from the transaction's produced forms — not from the HTTP acknowledgement alone.
• Update semantics. UpdateTransaction accepts the full transaction body. Treat it as a replace of the submitted transaction representation rather than a field-level merge; send the complete intended state.
• Dual identifier addressing. Anywhere a transactionId path parameter appears, either the integer ID or the UUID reference number is accepted. Be consistent within your own records to avoid confusion.
• Callback authenticity. When an HMAC key is configured for callbacks, Vitu signs the callback body using HMAC/SHA-256 (base64-encoded). If you rely on callbacks for state, verify the signature before acting. See the callback description in the spec.
• Polymorphic callbacks. The callback body is discriminated by callbackType. Branch on the discriminator; do not assume a single fixed shape. Some variants carry audit messages, shipment/indicia info, invoicing, or errors.
• Location scoping. Document and ticket operations require x-location-id. Requests without it, or with a location the caller cannot access, will fail authorization/validation.
• Blank form generation. DownloadTransactionDocument supports generating a blank version of a form. Use this deliberately; a blank form is not the filled transaction output.

7. Asynchronous / Callback Patterns

Flow. Register a callbackUrl on a write operation. Vitu processes the request in the background and POSTs a callback to your URL when the transaction's state changes. Your endpoint should return a success status to acknowledge receipt.

Correlation. Correlate callbacks to your original request using the reference number / transaction identifier carried in the callback body. Persist the reference number you used at create time so inbound callbacks can be matched.

Payload variants. The body is polymorphic, discriminated by callbackType (success, failure, and additional platform event types). Branch on the discriminator and handle unknown variants defensively.

Integrity. When an HMAC key is configured, verify the HMAC/SHA-256 signature before trusting the payload.

8. Environments & Sandbox Access

The spec defines a production environment plus staging and test variants selected through the host template's environment segment. Use the non-production environments for all integration and certification work; they exercise the same operations and contracts without producing state-filed results. Credentials and environment access are provisioned by Vitu via the Developer Portal's Key Management area. Refer to the spec's servers block for the exact environment values rather than hard-coding URLs.

--

9. Rate Limiting & Quotas

The API signals throttling with a dedicated "too many requests" response that includes a Retry-After header. When you receive it, pause for at least the indicated interval before retrying, and apply exponential backoff with jitter for repeated throttling. The spec defines the response and header; it does not publish fixed numeric quotas, so do not assume specific limits — design your client to react to the signal rather than to a hard-coded rate.

--

10. Error Handling & Troubleshooting

Errors use the spec's Errors / Error schema (or a simple code/message object on some responses). Handle by class rather than by individual code, since specific codes may change.

Backoff convention: start around 1s, double each attempt, add jitter, cap total attempts. Never retry 400/403/404 without changing the request.

11. Data Sensitivity & Compliance Notes

Transactions carry owner PII (names, residence and mailing addresses, and business identifiers such as FEIN) and vehicle identifiers (VIN). Transmit only over TLS, restrict storage and log exposure of these fields, and avoid persisting full payloads in plaintext logs. Callbacks may echo owner and vehicle data to your endpoint — secure that endpoint accordingly and verify HMAC signatures where configured. This is handling guidance, not legal advice; confirm your regulatory obligations independently.

12. Support & Resources

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