Driver License Data Verification (DLDV) - Developer Guide

1. Overview & Introduction

Driver License Data Verification (DLDV) verifies the authenticity and current status of a driver's license (or comparable identity document) against issuing-state records, returning a match confirmation and license status. It is intended for integrators who need to confirm that a presented license is genuine and valid before proceeding with a downstream business process.

The core noun in DLDV is the inquiry. An inquiry represents a single verification request: you submit identifying details about a document and its holder, DLDV checks those details against the relevant jurisdiction's records, and the result is made available for retrieval. Each inquiry carries a caller-supplied reference number (a UUID you generate) and, once accepted, a server-assigned inquiry identifier. Both can be used to locate the inquiry later. The verification outcome itself lives in the inquiry record, and a PDF report rendering of the result is also available.

DLDV is an asynchronous API. Submitting an inquiry does not return the verification result inline; it acknowledges acceptance of the request. The result becomes available afterward, either by retrieval or via an optional callback (see the async and workflow sections). Design your integration around this submit-then-collect pattern rather than expecting a synchronous answer.

The API is served across three environments — a production environment and two lower environments (staging and test) — distinguished by an environment variable in the server URL. Consult the spec's servers block for the exact host and environment tokens. All environments require OAuth 2.0 authentication.

Sensitive-data note. Inquiry inputs and results include personally identifiable information (names, dates of birth, document numbers) and verification outcomes. Treat request payloads, retrieved records, and PDF reports as regulated personal data in transit and at rest. Formal handling and compliance requirements are not specified in the source material — see the flag under Data sensitivity & compliance notes.

2. Getting Started / First Call

Prerequisites

• Vitu-issued OAuth 2.0 client credentials.
• The ability to make HTTPS REST calls and send a bearer token.
• A target environment (start with test or staging, not production).

Obtain access

Client credentials are obtained from the Key Management area within Vitu's Developer Portal. These credentials are used with the client-credentials grant to obtain an access token.

Minimal happy path

1. Obtain an access token using your client credentials against the token endpoint (see Authentication & access walkthrough).
2. Generate a reference number (a UUID) for your inquiry and call the inquiry-creation operation (createInquiry) with the required inputs. This is acknowledged asynchronously — it confirms the request was accepted, not that verification is complete.
3. Once processing completes, retrieve the inquiry using either the load-by-id or load-by-reference-number operation, keyed by the identifier you hold.
4. Retrieve the inquiry record (LoadInquiryRecord) to read the verification outcome, or fetch the PDF report (GetReport) if you need a rendered document.

Refer to the spec for the exact request body, required fields, and response shapes of each operation. Do not hardcode field lists from this document.

Illustrative sequence (conceptual)

POST inquiry-creation        → 202 Accepted (inquiry acknowledged)
   ... processing occurs asynchronously ...
GET  load-inquiry            → inquiry located, processing status visible
GET  load-inquiry-record     → verificationPassed + description available
GET  report (optional)       → PDF rendering

3. Authentication & Access Walkthrough

DLDV uses OAuth 2.0 with the client-credentials grant. The formal scheme is defined in the spec under the security scheme named oneVituOauth; consult it for the token URL and scope name. This is the only supported scheme — there is no API-key or user-interactive flow. If you expected an alternative, there isn't one.

Obtaining credentials. Client credentials are issued through the Key Management area of Vitu's Developer Portal.

Obtaining a token. Exchange your client credentials at the token endpoint defined in the spec, requesting the access scope named in the spec's scheme definition. The response is a bearer access token.

Attaching the token. Send the token as a bearer credential on every DLDV request. All operations require the scope declared in the spec.

Token lifecycle. Access tokens expire. Cache and reuse a token until shortly before its expiry, then request a fresh one; do not fetch a new token per request. The client-credentials grant issues application tokens directly, so plan to re-request rather than rely on a separate refresh token.

Retry on auth failure. If a call is rejected for missing or invalid authentication, obtain a fresh token and retry once. If it is rejected because the authenticated caller lacks permission, do not retry — this indicates a credential/authorization configuration issue, not an expired token.

Optional request headers. The inquiry-creation operation accepts optional headers identifying a Vitu location and a user on whose behalf the request is made. See the spec for their names and types. Use them when acting in a multi-location or delegated context.

4. Key Concepts & Glossary

Relationships and lifecycle.

• An inquiry is created first; everything else depends on it existing.
• The inquiry's record and report are derived artifacts — they are only meaningful once the inquiry has finished processing.
• Both the reference number (yours) and the inquiry identifier (the server's) point to the same inquiry. Retain the reference number you generate so you can correlate results even before you learn the server identifier.
• An inquiry moves conceptually from accepted → processing → completed (with a pass/fail outcome) or errored. The spec does not expose a discrete status enum; completion is inferred from the presence of a processed timestamp and/or the verification result. See the behavioral notes and the flag below.

5. Common Use Cases & Integration Patterns

Use case A - Verify a license and read the outcome (polling)

1. Create the inquiry (createInquiry) with the document and holder details. Retain your reference number.
2. Poll for completion using load-by-reference-number (LoadInquiryByRefNumber) or load-by-id (LoadInquiryById) until the inquiry shows it has been processed.
3. Retrieve the inquiry record (LoadInquiryRecord) to read the verification result.

Use this pattern when you cannot receive inbound callbacks.

Use case B - Verify a license with completion callback

1. Create the inquiry, supplying a callback URL (see Asynchronous / callback patterns).
2. Wait for the callback notification indicating the inquiry has been processed.
3. On receipt, retrieve the inquiry record (LoadInquiryRecord) — and optionally the report (GetReport) — to read and archive the outcome.

Prefer this pattern over polling when your integration can accept inbound HTTP.

Use case C - Produce an archival document

After an inquiry completes, fetch the report (GetReport) to obtain a PDF suitable for storage or human review. This complements, and does not replace, reading the structured record.

Ordering and dependencies (all use cases). Creation always precedes retrieval. The record and report are only reliable once the inquiry is complete; fetching them earlier may return incomplete or absent results.

6. Behavioral & Operational Notes

• Asynchronous acceptance. Inquiry creation acknowledges receipt; it does not return the verification outcome. Do not treat the creation response as the result.
• Completion is inferred, not enumerated. The spec exposes no explicit status field. Completion is signalled by a processed timestamp and the presence of a verification result on the record. Treat the presence of the verification outcome as the authoritative "done" signal.
• Two lookup keys, one inquiry. Loading by reference number and loading by identifier address the same inquiry. Choose whichever key you hold; results are equivalent.
• Verification outcome semantics. The record carries a pass/fail boolean and a human-readable description. A completed inquiry with a failed verification is a normal, successful API interaction — it means the document did not match records, not that the call failed.
• Errors surface in payloads, not only status codes. Both the callback and the inquiry response can carry an error field. Inspect these even on otherwise successful retrievals.

7. Asynchronous / Callback Patterns

DLDV can notify you when an inquiry finishes processing via a callback (defined in the spec on the inquiry-creation operation as the transactionCompleted callback). Conceptually:

• You supply a callback URL as part of inquiry creation; DLDV POSTs a completion notification to that URL when processing finishes.
• The notification payload correlates back to your inquiry via the reference number and inquiry identifier, and includes a processed timestamp and an optional error field.
• On receipt, retrieve the record (and optionally the report) to obtain the full result — treat the callback as a signal, not the complete result.

Corresponding DLDV Notifications product: The DLDV Notifications product serves as a complementary offering to this DLDV service. Together, the inquiry and notification capabilities provide a complete ecosystem for both initiating driver’s license data verification requests and staying informed of relevant updates through secure, automated notifications. See that product in the Catalog for more details.

8. Environments & Sandbox Access

DLDV exposes a production environment and two lower environments (staging and test), selected via the environment variable in the server URL — see the spec's servers block for exact tokens. Use a lower environment for integration and testing; promote to production only after validating your flow end to end. Access to all environments is gated by the same OAuth client-credentials scheme. Whether separate credentials are issued per environment is managed through the Key Management area of the Developer Portal.

9. Rate Limiting & Quotas

DLDV enforces rate limits; exceeding them yields the spec's rate-limit response (the TooManyRequests response). When you receive it, back off and retry after the limit window resets. The spec does not define a numeric limit or a named retry header; consult the API owner or response headers at runtime for the applicable window rather than hardcoding a value.

10. Error Handling & Troubleshooting

Errors are returned using the spec's error collection schema (the Errors array of Error items); rely on the message (and optional field) it carries rather than parsing status text. Handle failures by class:

Backoff convention. For retryable classes (rate-limit, server, transient auth), use exponential backoff with jitter and a capped maximum number of attempts. Do not retry validation or authorization failures.

Note: DLDV does not define a distinct not-found response in the spec; a request for a not-yet-processed inquiry may surface as a validation or empty result rather than an explicit 404. Handle "not yet available" defensively.

11. Data Sensitivity & Compliance Notes

DLDV processes and returns personal identity data and license-verification outcomes. At minimum: transmit only over TLS, restrict storage of records and PDF reports to what you require, and control access to verification results. Formal compliance obligations (retention limits, permissible use, jurisdictional restrictions) are not defined in the source material and are not provided here.

12. Support & Resources

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