Monitoring in-person verifications

In-person verification runs on the verifier's device. The holder's wallet and your app exchange data directly over Bluetooth, so the verification itself never passes through MATTR VII. To give you visibility of these verifications, the mDocs Verifier SDK reports each one to your MATTR VII tenant as an analytic event. You can then query these events alongside the rest of your tenant's events.

This page explains when the SDK reports an event, what the event includes, and how to query the events for an app, a device, or a single verification session.

It assumes you are familiar with how to query analytic events.

How it worksCopy Anchor Link

1. Your app calls sendProximityPresentationRequest to request credentials from the holder.
2. The holder's wallet returns a response, and the SDK verifies it on the device.
3. The SDK returns the verification result to your app.
4. In the background, the SDK reports a CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS event to your MATTR VII tenant.
5. MATTR VII records the event, and you can retrieve it using the Retrieve events endpoint.

The event name means the exchange with the holder completed and a response was verified. It does not mean every credential in the response passed verification. Check the verificationResult of each credential in the event to see the outcome.

What you can observeCopy Anchor Link

Most of an in-person verification happens between the holder's wallet and your app, without contacting MATTR VII. The following table shows which steps reach your tenant and emit events.

Steps 3 to 5 leave no trace on your tenant until step 6 reports the outcome. A session that ends before the holder responds produces no event at all.

When an event is reportedCopy Anchor Link

The SDK reports one event for each call to sendProximityPresentationRequest that returns a response. A single proximity presentation session can include more than one request, so a session can produce more than one event.

No event is reported when sendProximityPresentationRequest throws an error.

The SDK sends each event in the background, so reporting never delays or changes the result returned to your app. If an event cannot be delivered, for example because the device is offline, the SDK logs the failure and does not retry. Use these events for monitoring and reporting, not as a complete record of every verification.

What an event includesCopy Anchor Link

Each event describes the exchange, not the holder's personal information. Claim values are never included.

• Included:
  • The requested credential types and claims.
  • For each returned credential, its type, verification result, validity dates, and issuer details.
  • Any requested claims or credentials that the holder did not return.
  • How the holder's device was engaged (NFC or QR).
• Not included:
  • Claim values, such as names, dates of birth or portraits.
  • Credential branding.

MATTR VII adds the following attribution to each event when it records it. These values come from the SDK's registration with your tenant, not from the event payload.

• applicationId: The verifier application the app is registered against.
• applicationInstanceId: The specific installation of your app on a device.
• data.platform: The device platform, such as ios.
• data.sdkVersion: The name and version of the SDK that sent the event, such as verifier-sdk-ios/6.1.0.
• data.receivedAt: When MATTR VII received the event.

Example eventCopy Anchor Link

The following is an example of the event as returned by the Retrieve events endpoint. In this example, the verifier requested an mDL and a Photo ID. The holder returned the mDL without the portrait, and did not return the Photo ID.

{
  "id": "5f9c0b1e-3d7a-4f2b-9c8e-1a2b3c4d5e6f",
  "type": "CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS",
  "category": "credential-presentation",
  "timestamp": "2026-09-02T10:14:32.187Z",
  "createdAt": "2026-09-02T10:14:33.402Z",
  "requestId": "0b6f2c8e-4a1d-4e97-b3c5-8d2f6a9e1c40",
  "applicationId": "7d2e4c81-5b3f-4a19-8e6d-0f1a2b3c4d5e",
  "applicationInstanceId": "c3a9f1d7-8b24-4e05-9f3a-6d7c8e9f0a1b",
  "sessionId": "b4e1c9a7-2f61-4d08-9a3e-7c5b1f0e2d94",
  "data": {
    "sessionId": "b4e1c9a7-2f61-4d08-9a3e-7c5b1f0e2d94",
    "engagementMethod": "QR",
    "credentialQuery": [
      {
        "profile": "mobile",
        "docType": "org.iso.18013.5.1.mDL",
        "nameSpaces": {
          "org.iso.18013.5.1": {
            "given_name": { "intentToRetain": false },
            "family_name": { "intentToRetain": false },
            "portrait": { "intentToRetain": false }
          }
        }
      },
      {
        "profile": "mobile",
        "docType": "org.iso.23220.photoid.1",
        "nameSpaces": {
          "org.iso.23220.1": {
            "age_over_18": { "intentToRetain": false }
          }
        }
      }
    ],
    "credentials": [
      {
        "docType": "org.iso.18013.5.1.mDL",
        "validityInfo": {
          "signed": "2026-01-15T10:00:00.000Z",
          "validFrom": "2026-01-15T10:00:00.000Z",
          "validUntil": "2027-01-15T10:00:00.000Z"
        },
        "claimErrors": {
          "org.iso.18013.5.1": { "portrait": "notReturned" }
        },
        "issuerInfo": {
          "commonName": "Example State Department of Motor Vehicles",
          "certificateFingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
        },
        "verificationResult": { "verified": true }
      }
    ],
    "credentialErrors": [
      { "docType": "org.iso.23220.photoid.1", "errorCode": "notReturned" }
    ],
    "applicationId": "7d2e4c81-5b3f-4a19-8e6d-0f1a2b3c4d5e",
    "applicationInstanceId": "c3a9f1d7-8b24-4e05-9f3a-6d7c8e9f0a1b",
    "platform": "ios",
    "sdkVersion": "verifier-sdk-ios/6.1.0",
    "receivedAt": "2026-09-02T10:14:33.398Z"
  }
}

• credentials[].verificationResult: Whether the credential passed verification on the device. When verified is false, a reason explains why. Refer to Handling verification results for the possible values.
• credentials[].claimErrors: Requested claims that the holder did not return.
• credentials[].issuerInfo.certificateFingerprint: The SHA-256 fingerprint of the IACA certificate the credential was verified against. Use it to identify which trusted issuer the credential came from.
• credentialErrors: Requested credentials that the holder did not return.

TimestampsCopy Anchor Link

Each event has two timestamps:

• timestamp: When the verification happened, according to the device clock.
• createdAt: When MATTR VII recorded the event.

The two can differ significantly if the device clock is wrong, or if the event was delivered some time after the verification. This means an event can be recorded after you have already queried the time window it belongs to. The dateFrom and dateTo query parameters filter on timestamp, so a date-bounded query run before a late event arrives will not include it.

IdentifiersCopy Anchor Link

Use these identifiers to group events at different levels.

The requestId of these events is generated by the SDK for each verification. It is not related to the x-request-id header of any HTTP call.

Query in-person verification eventsCopy Anchor Link

All the examples below use the Retrieve events endpoint. You can combine them with any of the other query parameters described in How to query analytic events.

All verifications for a verifier applicationCopy Anchor Link

GET /v1/events?types=CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS&applicationIds=7d2e4c81-5b3f-4a19-8e6d-0f1a2b3c4d5e

All verifications from one deviceCopy Anchor Link

Use this to investigate an issue reported from a specific device, or to review the activity of a single installation of your app.

GET /v1/events?types=CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS&applicationInstanceIds=c3a9f1d7-8b24-4e05-9f3a-6d7c8e9f0a1b

You can retrieve the instance IDs registered against a verifier application using the Retrieve verifier application instances endpoint.

All verifications in one sessionCopy Anchor Link

GET /v1/events?sessionIds=b4e1c9a7-2f61-4d08-9a3e-7c5b1f0e2d94

Next stepsCopy Anchor Link