Skip to content

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.

Rendering diagram...

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.

POST /v1/diw/verifications

Every 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:

FieldTypeRequiredDescription
refstringYesThe 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=..."
}
FieldDescription
idThe id of this verification. Send the full value back when you query the result.
qrcode_imageThe QR code image (base64 PNG data URI) to show on desktop web pages.
auth_uriThe 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.

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.

{
"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" }
]
}
]
}
FieldTypeDescription
verify_resultbooleantrue means verification passed. false means verification failed. If result_description is present, it gives the reason.
result_descriptionstring (optional)The text that describes the verification result, passed on unchanged. This field can be missing.
holder_didstring (optional)The DID of the holder. This field can be missing.
transaction_idstringThe same value as the id that you used for the query.
data[]arrayThe 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[].cidstringThe identifier of this credential.
data[].credential_typestringThe credential type identifier from the verification result, passed on unchanged.
data[].claims[]arrayThe fields that the holder presented. The verification scenario specifies which fields appear.
claims[].enamestringThe English name of the field.
claims[].cnamestringThe Chinese name of the field.
claims[].valuestringThe 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 cid to compare. Use verify_result, credential_type, and claims to 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:

  1. After issuance, store the credential_serial that GET /v1/diw/issuances/{id} returns.
  2. When you verify, the presented credential is the one you expect only if data[].cid equals the credential_serial that 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.

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.