Skip to main content
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:
  • 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 TypeDescription
201application/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 CodeResponse MessageDescription
201Verification is initiated successfullyThe response body contains the Response Schema defined above.
400Bad RequestThe request is malformed or invalid.
401UnauthorizedThe request requires authentication. Ensure a valid access token is provided in the Authorization header.
403ForbiddenInsufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404Template not foundThe provided template ID is invalid or no longer active.
500Internal Server ErrorAn 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 TypeDescription
200application/jsonstate: 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 CodeResponse MessageDescription
401UnauthorizedThe request requires authentication. Ensure a valid access token is provided in the Authorization header.
403UnauthorizedInsufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.
404Verification not foundThe provided verification ID is invalid or no longer active.
500Internal Server ErrorVerification failed. Response body may contain an ErrorResponse object with details about the failure. Check the reason field for specific error information.
⌘I