Mobile Driver's License Verification API

This API facilitates interactions with a digital wallet for mDL verifiable credentials, following Annex A of the ISO/IEC TS 18013-7:2024 standard (REST API). The purpose of this API is to simplify credential exchange as much as possible. It achieves this by abstracting and managing the trust relationship with credential issuers and implementing the complex protocol that verifies and communicates with a compliant wallet.

The primary function is to initiate and manage verifications and report their status to the requesting party. This allows the complex interactions between reader and wallet to be abstracted from the act of verifying a document. The reader (website) initiates a verification, and the Mobile Driver’s License Verification API responds with a Verification ID and an engagement URI for communication with the wallet.  The reader can then begin polling the API for receiving claims. This API exclusively uses application/json for request and response bodies.

Create verification request

This endpoint initiates a new verification process.  It accepts a POST request specifying the desired protocol for interacting with the wallet and a template ID referencing a pre-configured verification template.

The response includes a verification ID along with an engagement URI for engaging the wallet based on the specified protocol.

Endpoint

POST /vdcs/verification

Scopes

create:verification_request

Body parameters

• protocol: String. Required
  

  Engagement protocols define the methods your application uses for interacting with the wallet. We currently support:

  • mdoc/webapi/draft-2023-03-29: Uses an MDoc URI as defined in ISO/IEC DTS 18013-7 for communication.
  • mdoc/webapi/v1.0: Uses an MDoc URI as defined in ISO/IEC DTS 18013-7 for communication.

• template_id: String. Required
  

  The ID references a pre-configured template. This simplifies the request by using pre-defined claim requirements.

Response schema

Response Code	Response Type	Description
201	application/json	verification_idString Verification ID (UUIDv4) as received from the verification initiation. This ID is used for subsequent interactions with the verification API, such as polling for status. engagementString MDoc URI for the Web API protocol. This URI should be presented to the user to initiate the wallet interaction using the protocols. It conforms to the structure defined in ISO/IEC DTS 18013-7 (Annex 4)

Response codes

Response Code	Response Message	Description
201	Verification is initiated successfully	The response body contains the Response Schema defined above.
400	Bad Request	The request is malformed or invalid.
401	Unauthorized	The request requires authentication. Ensure a valid access token is provided in the Authorization header.
403	Forbidden	Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404	Template not found	The provided template ID is invalid or no longer active.
500	Internal Server Error	An unexpected error occurred on the server.

Get verification status

This endpoint retrieves the status and, if available, the claims of a given verification.  The id path parameter specifies the Verification ID.

Endpoint

GET /vdcs/verification/{id}

Scopes

read:verification_request

Path parameters

verification_id: String. Required

• Verification ID (UUIDv4) as received from the verification initiation. This ID is used for subsequent interactions with the Mobile Driver’s License Verification API, such as polling for status.

Response schemas

Response Code	Response Type	Description
200	application/json	state: String Required The state field contains information about the current state of the verification process. The following values may be present: pending-engagement: The verification service is waiting initial engagement from the wallet. pending-mdoc: The verification service is waiting presentation of the mDoc from the wallet. error-wallet: An error occurred when interacting with the wallet. The reason field will contain more information regarding the encountered error. error-reader: An error has occurred when reading the mDoc. The reason field will contain more information regarding the error encountered. honored: Verification completed without issue. The verified document is available in the presentation field for consumption. reason: String Optional The reason field contains additional information (if available) regarding the state of the verification request. presentation: Object Optional The presentation field contains the claims provided by the wallet in response to the presentation definition. It follows a simplified structure based on namespaces and claims. Each claim includes a value, retain flag, and verified status.

Response codes

Response Code	Response Message	Description
401	Unauthorized	The request requires authentication. Ensure a valid access token is provided in the Authorization header.
403	Unauthorized	Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404	Verification not found	The provided verification ID is invalid or no longer active.
500	Internal Server Error	Verification failed. Response body may contain an ErrorResponse object with details about the failure. Check the reason field for specific error information.