Verification API
The verification flow: you create a verification request. The holder scans with the Taiwan Digital Identity Wallet (TW DIW, “the wallet” in this handbook), selects a credential, and consents to present it. Your backend polls TCS API for DIW until it gets the result or the timeout ends.
In the diagram, par means that the steps occur at the same time, loop means that the steps repeat, and alt means that only one of the paths occurs, depending on the situation.
Create a verification request
Section titled “Create a verification request”POST /v1/diw/verificationsEvery request must include X-API-Key. Also include x-correlation-id, and put the same value in x-request-id. A POST request must also include Content-Type: application/json. See API Basics.
The request body has one field only:
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | The code of the verification scenario (VP Template). Your organization requests it, and the TCS team creates it and gives it to you. See Request new credential types and verification scenarios. It specifies which credentials and which fields the holder must present. |
{ "ref": "<ref>"}ref must be a non-empty string. If it is missing, empty, or not a string, you get 400. If the body contains other fields, you also get 400.
If the verification scenario is not found, you get 400 with error code 10102. For other status codes and what to do, see Errors and Polling.
On success, you get 201:
{ "id": "<id>", "qrcode_image": "data:image/png;base64,iVBORw0K...", "auth_uri": "https://frontend.wallet.gov.tw/api/moda/vpqrcode?mode=vp01&deeplink=..."}| Field | Description |
|---|---|
id | The id of this verification. Send the full value back when you query the result. |
qrcode_image | The QR code image (base64 PNG data URI) to show on desktop web pages. |
auth_uri | The mobile link. When the holder opens this https link on a phone, the phone opens the wallet app. It has the same content as the QR code. |
For how to use the id, the QR code, and the mobile link, see API Basics.
Poll for the result
Section titled “Poll for the result”GET /v1/diw/verifications/{id}Put the id that you got when you created the verification in {id}. Do not change it. If the holder has not completed, you get 200:
{ "status": "pending", "id": "<id>"}status has two values only: pending and completed.
pending: the holder has not completed. Query again after 2 to 5 seconds.completed: the result is available. See the next section for how to read it.
If the holder does not scan, or the wallet does not let the holder select a credential, the status stays pending (waiting) for the full timeout that you set. Set your own timeout. The recommended value is 5 minutes. When the time is up, stop polling and ask the holder to start again.
Only the account that created this verification request can query the result. If you use the API Key of a different account to query the same id, you get 404.
Read a completed result
Section titled “Read a completed result”{ "status": "completed", "verify_result": true, "result_description": "success", "holder_did": "did:key:z...", "transaction_id": "<transaction_id>", "data": [ { "cid": "<cid>", "credential_type": "2-16-886-101-20003-20008-20082_driverlicense_car_1211", "claims": [ { "ename": "name", "cname": "姓名", "value": "<姓名>" }, { "ename": "license_type", "cname": "駕照種類", "value": "汽車(普小)" }, { "ename": "issued_date", "cname": "發照日期", "value": "110.03.15" } ] } ]}| Field | Type | Description |
|---|---|---|
verify_result | boolean | true means verification passed. false means verification failed. If result_description is present, it gives the reason. |
result_description | string (optional) | The text that describes the verification result, passed on unchanged. This field can be missing. |
holder_did | string (optional) | The DID of the holder. This field can be missing. |
transaction_id | string | The same value as the id that you used for the query. |
data[] | array | The credentials that the holder presented, one item for each credential. If the verification scenario asks for more than one credential type, there are more items. Read all items, not only the first item. |
data[].cid | string | The identifier of this credential. |
data[].credential_type | string | The credential type identifier from the verification result, passed on unchanged. |
data[].claims[] | array | The fields that the holder presented. The verification scenario specifies which fields appear. |
claims[].ename | string | The English name of the field. |
claims[].cname | string | The Chinese name of the field. |
claims[].value | string | The field value. It is always a string, exactly as the holder presented it. |
The wallet always sends the credential serial number (憑證序號). The holder cannot untick this item.
Values on a credential can contain full-width parentheses (for example 汽車(普小)) or ROC calendar dates (for example 110.03.15). Do not assume a format for value.
Compare the cid only for credentials that you issued
Section titled “Compare the cid only for credentials that you issued”- You need to confirm that the holder presented a specific credential that you issued (for example, because you revoked one of them): always compare the
cid. See the method below. - You verify credentials that other organizations issued (for example, a driver’s license): you have no
cidto compare. Useverify_result,credential_type, andclaimsto decide whether to accept the credential.
A successful verification (verify_result: true) only means that the credential that the holder presented is valid. It does not mean that it is the credential you expect. The holder’s wallet may contain two credentials of the same credential type. After you revoke the credential that you issued to the holder, the holder can still present another valid credential. In this case, the verification passes (verify_result: true), but data[].cid is the cid of the other credential.
If you issued this credential through the Issuance API, compare as follows:
- After issuance, store the
credential_serialthatGET /v1/diw/issuances/{id}returns. - When you verify, the presented credential is the one you expect only if
data[].cidequals thecredential_serialthat you stored.
Do not compare with the cid from issuance. The two formats are different, so they are never equal.
For the full behavior after revocation, see Revoke API.
Expired results return 410
Section titled “Expired results return 410”About 5 minutes after the verification completes, the result is cleared. If you then query the same id, you get 410 (error is Gone).
When you get 410, you cannot get the result back. Create a new verification request and ask the holder to scan again.
To avoid 410, query every 2 to 5 seconds while the QR code is on the screen. When you get completed, immediately store the fields that you need.