Vehicle History Verification (NMVTIS) - Notifications

1. Overview & Introduction

The NMVTIS Notifications API lets your integration receive asynchronous event notifications when NMVTIS vehicle history data relevant to a submitted request becomes available or is updated. Rather than repeatedly polling for results, you register a callback endpoint (a webhook) and Vitu delivers notifications to it as data changes.

The domain model is small and centers on two nouns:

• Subscription — the registration that binds your integration to a single callback URL. It represents "where Vitu should deliver notifications." The subscription-retrieval operation exposes the currently registered callback URL; the subscribe and unsubscribe operations manage its lifecycle.
• Callback security configuration — the settings that tell Vitu how to authenticate and secure delivery to your callback endpoint (for example, Basic auth, HMAC signing, OAuth client credentials, custom headers, or mTLS). This is configuration you provide about your own receiving endpoint; it is distinct from how you authenticate to Vitu.

Directionality note. This API involves two authentication directions. You authenticate to Vitu using OAuth 2.0 client credentials (see §3). Vitu authenticates to your callback endpoint using whatever you configure via the callback-security operation. Do not conflate the two.

Environments are selected through the env server variable and correspond to production (api), staging (api-stage), and test (api-test). See the spec's servers block for exact URLs. Credentials are issued per environment by Vitu.

Because this API concerns NMVTIS vehicle history data, treat both the notification payloads delivered to your callback and the data they reference as potentially regulated. See §Data sensitivity & compliance notes.

2. Getting Started / First Call

Prerequisites

• A Vitu-issued OAuth 2.0 client credential (client ID and secret). Obtain these from the Key Management area within Vitu's Developer Portal.
• A publicly resolvable HTTPS callback endpoint you control, capable of receiving notification requests.

Minimal happy path

1. Obtain a token. Exchange your client credentials for an access token at the token endpoint defined by the oneVituOauth scheme (see §3).
2. Configure callback security (recommended before subscribing). Use the callback-security operation (SetCallbackSecurity) to tell Vitu how to authenticate to your endpoint. See §3 and §5 for why this should come first.
3. Subscribe. Call the Subscribe operation, supplying your callback URL. On success the subscription is registered.
4. Confirm. Call the GetSubscription operation to verify the registered callback URL.
5. Receive notifications. Vitu delivers event notifications to your callback endpoint as NMVTIS data becomes available or is updated.

Note: The completion callback's payload is CallbackDTO; its refNumber and inquiryID map directly to the Inquiry product's retrieval operations.

Corresponding NMVTIS Inquiry product: The Vehicle History Verification (NMVTIS) product serves as a complementary offering to this NMVTIS Notifications service. Together, the inquiry and notification capabilities provide a complete ecosystem for both initiating vehicle history verification requests and staying informed of relevant updates through secure, automated notifications. See that product in the Catalog for more details.

3. Authentication & Access Walkthrough

The formal scheme is defined in the spec as oneVituOauth (OAuth 2.0 client credentials grant), with the scope oneapi:access. Do not treat the following as a redefinition — it is operational guidance.

Obtaining credentials

Client credentials are issued by Vitu and are retrieved from the Key Management area within Vitu's Developer Portal. Credentials are environment-specific.

Obtaining and attaching a token

1. POST your client ID and secret to the token endpoint defined in the oneVituOauth scheme, requesting the oneapi:access scope.
2. Attach the returned access token as a Bearer token on every request to this API.

Token lifecycle

• Access tokens expire. Cache and reuse a token until shortly before expiry, then request a new one.
• On an authentication failure (the spec's 401 response), obtain a fresh token and retry once. If it still fails, treat the credential as invalid rather than retrying in a loop.

Environment differences

Each environment (api, api-stage, api-test) uses its own credentials and base URL.

Only one scheme (oneVituOauth) exists for authenticating to this API. There is no API-key or Basic alternative for inbound calls. (Basic, HMAC, OAuth, and mTLS options in the spec's schemas apply only to outbound callback delivery to your endpoint — see §4 and §5.)

4. Key Concepts & Glossary

Relationships and lifecycle

• Callback security is configuration about your endpoint; a subscription is where deliveries go. Configure security first, then subscribe (see §5), so no delivery ever occurs against an unsecured endpoint.
• The subscription is effectively a single registration keyed to the callback URL exposed by the get-subscription operation. Subscribe registers it; unsubscribe removes it.

5. Common Use Cases & Integration Patterns

Scenario A - Stand up notification delivery (first-time setup)

1. Configure callback security (SetCallbackSecurity) — establish how Vitu will authenticate to your endpoint (Basic, HMAC, OAuth, headers, and/or mTLS) before any delivery can occur.
2. Subscribe (Subscribe) — register your HTTPS callback URL.
3. Verify (GetSubscription) — confirm the registered URL.
4. Handle inbound notifications at your endpoint.

Intent: securing the endpoint before subscribing prevents Vitu from delivering to an unauthenticated receiver.

Scenario B - Rotate callback security (e.g., new HMAC key or credentials)

1. Update your receiver to accept both old and new secrets during the transition.
2. Configure callback security (SetCallbackSecurity) with the new settings.
3. Retire acceptance of the old secret once you have confirmed deliveries succeed.

Intent: avoid a window where in-flight deliveries fail verification.

Scenario C - Change destination endpoint

1. Configure callback security for the new endpoint (SetCallbackSecurity).
2. Subscribe (Subscribe) with the new callback URL.

Scenario D - Tear down

1. Unsubscribe (Unsubscribe) to stop deliveries.

Pattern guidance

This API is push (webhook), not poll. Your integration should host a resilient, idempotent receiver rather than polling for results. Correlate incoming notifications back to your original NMVTIS requests using identifiers carried in the payload.

6. Behavioral & Operational Notes

• Callback delivery is asynchronous. Notifications arrive at your endpoint at an unspecified later time relative to the underlying data change. Do not assume synchronous or ordered delivery unless the API owner confirms it.
• Configure security before subscribing. Subscribing first can expose your endpoint to unauthenticated deliveries.
• HTTPS is enforced for callback URLs. The spec constrains the callback URL to an https:// scheme.
• HMAC header is configurable. If you enable HMAC, the signature is placed in the header you name, defaulting to X-HMAC (per the HMAC settings schema). Verify signatures on every inbound delivery.
• Receiver idempotency. Because retries and duplicate deliveries are common in webhook systems, design your receiver to tolerate duplicate notifications.

7. Rate Limiting & Quotas

The spec defines a rate-limit response (429, TooManyRequests) but does not publish specific limits or documented rate-limit headers. When you receive the rate-limit response, back off and retry after the window resets. Read any rate-limit headers present on the response at runtime rather than hard-coding values.

8. Error Handling & Troubleshooting

Errors use the spec's Errors / Error schema (a list of messages, each optionally tied to a field). Handle by class, not by memorizing codes:

Use exponential backoff with jitter for retryable classes. Do not retry validation failures.

9. Data Sensitivity & Compliance Notes

NMVTIS vehicle history data is regulated. Notification payloads delivered to your callback may reference or contain such data. Handling expectations:

• Terminate callback delivery on HTTPS only (enforced) and prefer HMAC or mTLS to guarantee authenticity and integrity.
• Restrict access to received notification data to authorized systems and personnel.
• Do not log full payloads in systems that are not authorized to retain regulated data.

This is handling guidance, not legal advice. Confirm your specific NMVTIS compliance obligations with the API owner and your compliance function.

10. Support & Resources

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