Motor Vehicle Record (MVR) Verification - Notifications

1. Overview & Introduction

The MVR Verification Notifications API lets your integration receive asynchronous event notifications when a requested motor vehicle record becomes available or is updated. Instead of repeatedly polling for the state of an MVR request, you register a callback endpoint and Vitu delivers events to it as they occur.

The domain model centers on two nouns:

• A subscription represents your registration to receive transaction notifications at a callback URL you control. There is a single subscription per authenticated client (the subscription-management operations operate on "your subscription," not on a collection of arbitrary subscriptions).
• A callback security configuration describes how Vitu authenticates itself to your callback endpoint when it delivers events. This is distinct from the OAuth credentials you use to call Vitu.

Note the directional split of trust: OAuth (scheme oneVituOauth) secures your calls to Vitu; the callback security configuration secures Vitu's calls to you. These are configured independently.

The API is served across three environments — production (api), staging (api-stage), and test (api-test) — distinguished by an environment variable in the server URL (see the spec's servers block for exact values). All environments require OAuth 2.0 client-credentials authentication.

Sensitive-data note: MVR data is regulated personal information. Your callback endpoint receives records over HTTPS (the spec enforces an https:// callback URL). Secure the receiving endpoint and the credentials it stores accordingly. See Data sensitivity & compliance.

2. Getting Started / First Call

Prerequisites

• OAuth 2.0 client credentials issued by Vitu. Obtain these from the Key Management area within Vitu's Developer Portal.
• A publicly resolvable HTTPS endpoint you control, ready to receive notification deliveries.

Minimal happy path

1. Obtain an access token from the Vitu token endpoint using the client-credentials grant (see the oneVituOauth scheme in the spec for the token URL and scope).
2. (Recommended) Configure callback security using the callback-security operation, so Vitu can authenticate its deliveries to your endpoint. See Authentication & access walkthrough.
3. Subscribe using the subscribe operation, supplying your callback URL. Vitu will deliver notifications to that URL as records become available or change.
4. Verify the registration with the get-subscription operation, which returns the currently registered callback URL.

Refer to the spec for the exact request and response shapes of each operation.

Once subscribed, no further polling is required — events arrive at your callback endpoint asynchronously.

3. Authentication & Access Walkthrough

There are two authentication surfaces in this API. Do not confuse them.

3.1 Authenticating your calls to Vitu (inbound)

All operations require OAuth 2.0 client-credentials, defined formally in the spec as the oneVituOauth security scheme with scope oneapi:access.

• Obtain credentials from the Key Management area within Vitu's Developer Portal.
• Get a token by calling the token endpoint declared in the oneVituOauth scheme with the client-credentials grant.
• Attach the token as a bearer credential on each request.
• Token lifecycle: Tokens expire. Cache a token and reuse it until near expiry, then request a new one. On an authentication failure response (see the spec's 401 responses), obtain a fresh token and retry once; if it still fails, treat it as a credential/config problem rather than retrying in a loop.

Flag — single scheme only: The spec defines exactly one security scheme (oneVituOauth). There is no API-key or alternative flow. Developers expecting alternatives should not look for one.

3.2 Authenticating Vitu's deliveries to your endpoint (outbound callbacks)

The callback-security operation lets you tell Vitu how to authenticate itself when it POSTs to your callback URL. The spec's CallbackSecuritySettingsDTO supports several mechanisms, which may be combined:

• HMAC signing — Vitu signs deliveries with a shared key (see HmacSettingsDTO; SHA-256 per the operation description). A custom signature header name is supported.
• Basic auth — credentials Vitu presents to your endpoint (BasicAuthSettingsDTO).
• OAuth client-credentials — Vitu obtains a token from your authorization server before delivering (ClientCredentialsOAuthSettingsDTO).
• Static security headers — fixed header name/value pairs (HeaderDTO).
• mTLS — Vitu presents a client certificate and optionally validates your server cert against a supplied CA bundle (MtlsSettingsDTO).

Refer to the spec for the exact field set of each mechanism. Configure callback security before or at the same time as subscribing, so your first delivery is already authenticated as expected.

4. Key Concepts & Glossary

Relationships and lifecycle

• Callback security and the subscription are configured independently but both target the same outbound delivery channel. Set security first so deliveries are authenticated from the start.
• The subscription lifecycle is: subscribe → (active, receiving deliveries) → unsubscribe. Re-subscribing updates the registered callback URL.

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

5. Common Use Cases & Integration Patterns

Use case A - Start receiving MVR notifications

1. Configure callback security via the callback-security operation (choose one or more mechanisms your endpoint can verify).
2. Register your callback URL via the subscribe operation.
3. Confirm registration via the get-subscription operation.
4. Handle inbound deliveries at your endpoint; verify them using the security mechanism you configured.

Pattern: This API is push-based. Prefer the callback/webhook flow over polling — there is no operation to poll individual record states here; availability is signaled by delivery.

Use case B - Rotate or change your callback endpoint

1. Update callback security if the new endpoint uses different credentials.
2. Call the subscribe operation with the new callback URL to update the registration.
3. Verify with the get-subscription operation.

Use case C - Stop receiving notifications

1. Call the unsubscribe operation. Deliveries cease for your subscription.

6. Behavioral & Operational Notes

• Async timing / eventual consistency: Notifications are asynchronous. There is no stated guarantee of how quickly a delivery follows an underlying record change. Design your endpoint to accept deliveries at any time.
• Single subscription semantics: The subscription operations act on the caller's own subscription. Calling the subscribe operation again is a replace/update of the registered callback URL, not an addition to a list.
• HTTPS enforced: The callback URL is constrained to https:// by the spec's pattern. Plain HTTP endpoints will be rejected.
• Callback security is combinable: Multiple mechanisms in the callback-security configuration can coexist (e.g. HMAC + static headers). Your endpoint must be prepared to satisfy whatever you configure.
• HMAC header name: If you enable HMAC without specifying a header name, Vitu uses a default signature header (see HmacSettingsDTO in the spec). Set the header name explicitly if your receiver expects a specific one.

7. Rate Limiting & Quotas

All operations can return a rate-limit response (the spec's TooManyRequests / 429 response). When you receive it, stop issuing requests until the window resets, then resume with exponential backoff. Any rate-limit headers and exact limits, if present, are defined by the platform rather than this spec — read them from the response at runtime rather than hard-coding values.

8. Pagination Conventions

The get-subscription operation accepts the shared limit and offset query parameters (see LimitParam and OffsetParam in the spec) for offset-based paging. Use offset to advance pages and limit to size them; defaults and bounds are defined in the spec.

9. Error Handling & Troubleshooting

Errors use the spec's Errors array schema (a list of Error objects, each carrying a message). Handle by class rather than by specific code:

10. Data Sensitivity & Compliance Notes

MVR data is regulated personal information delivered to an endpoint you control. Terminate deliveries over TLS, authenticate them using the callback security mechanisms above, restrict who can read the received data, and store any callback credentials securely. This is operational guidance, not legal advice; confirm your regulatory obligations independently.

11. Support & Resources

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