> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-quickstart-revamp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes the Mobile Driver's License Verification API.

# 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](https://www.iso.org/standard/82772.html) 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. <span class="label label-danger">Required</span><br />

  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](https://www.iso.org/standard/82772.html) for communication.
  * `mdoc/webapi/v1.0`: Uses an MDoc URI as defined in  [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html) for communication.

* **`template_id`**: String. <span class="label label-danger">Required</span><br />

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

### Response schema

<table class="table">
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b> Response Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>201</code></td>
      <td><code>application/json</code></td>
      <td><ul><li> <b><code>verification\_id</code></b>String <p> Verification ID <a href="https://www.npmjs.com/package/short-uuid">(UUIDv4)</a> as received from the verification initiation. This ID is used for subsequent interactions with the verification API, such as polling for status.</p></li><li><b><code>engagement</code></b>String <p> 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 <a href="https://www.iso.org/standard/82772.html">ISO/IEC DTS 18013-7 (Annex 4)</a></p></li></ul></td>
    </tr>
  </tbody>
</table>

### Response codes

<table class="table">
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b>Response Message</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>201</code></td>
      <td><code>Verification is initiated successfully</code></td>
      <td>The response body contains the <b>Response Schema</b> defined above.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td><code>Bad Request</code></td>
      <td>The request is malformed or invalid.</td>
    </tr>

    <tr>
      <td><code>401</code></td>
      <td><code>Unauthorized</code></td>
      <td>The request requires authentication.  Ensure a valid access token is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>Forbidden</code></td>
      <td>Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>404</code></td>
      <td><code>Template not found</code></td>
      <td>The provided template ID is invalid or no longer active.</td>
    </tr>

    <tr>
      <td><code>500</code></td>
      <td><code>Internal Server Error</code></td>
      <td>An unexpected error occurred on the server.</td>
    </tr>
  </tbody>
</table>

## 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. <span class="label label-danger">Required</span>

* Verification ID [(UUIDv4)](https://www.npmjs.com/package/short-uuid) 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

<table class="table">
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b> Response Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>200</code></td>
      <td><code>application/json</code></td>
      <td><b><code>state</code></b>: String <span class="label label-danger">Required</span> <p>The state field contains information about the current state of the verification process. The following values may be present: </p><ul><li><b><code>pending-engagement</code></b>: The verification service is waiting initial engagement from the wallet.</li><li><b><code>pending-mdoc</code></b>: The verification service is waiting presentation of the mDoc from the wallet.</li> <li><b><code>error-wallet</code></b>: An error occurred when interacting with the wallet. The <code>reason</code> field will contain more information regarding the encountered error.</li> <li><b><code>error-reader</code></b>: An error has occurred when reading the mDoc. The <code>reason</code> field will contain more information regarding the error encountered.</li><li><b><code>honored</code></b>: Verification completed without issue. The verified document is available in the <code>presentation</code> field for consumption.</li></ul> <br /> <b><code>reason</code></b>: String <span class="label label-primary">Optional</span><p> The <code>reason</code> field contains additional information (if available) regarding the state of the verification request. </p><p> <b><code>presentation</code></b>: Object <span class="label label-primary">Optional</span></p><p> The <code>presentation</code> 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 <code>value</code>, <code>retain</code> flag, and <code>verified</code> status.</p></td>
    </tr>
  </tbody>
</table>

### Response codes

<table class="table">
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b>Response Message</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>401</code></td>
      <td><code>Unauthorized</code></td>
      <td>The request requires authentication.  Ensure a valid access token is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>Unauthorized</code></td>
      <td>Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>404</code></td>
      <td><code>Verification not found</code></td>
      <td>The provided verification ID is invalid or no longer active.</td>
    </tr>

    <tr>
      <td><code>500</code></td>
      <td><code>Internal Server Error</code></td>
      <td>Verification failed. Response body may contain an <code>ErrorResponse</code> object with details about the failure.  Check the <code>reason</code> field for specific error information.</td>
    </tr>
  </tbody>
</table>