Skip to main content

Use a BIG Register Credential

The Story

Sophie has been a registered physiotherapist for a few months now, and her BIG registration credential sits safely in her personal wallet. Today is a big day — she is applying for a position at Amsterdam UMC, one of the largest academic hospitals in the Netherlands.

In the past, the onboarding process would have been a bureaucratic maze. Sophie would bring printed copies of her BIG certificate, the HR department would manually check a government database, and days would pass before anyone could confirm her qualifications. Forms would get lost, staff would be delayed, and patients would wait longer for care.

But Amsterdam UMC has integrated verifiable credential verification into their onboarding portal, powered by the Credenco Business Wallet. When Sophie starts her application, the portal simply asks her to prove her BIG registration. A QR code appears on her screen. She opens her wallet app, scans the code, and with a single tap chooses to share her BIG credential. Within seconds, the hospital's system has cryptographically verified her registration — no phone calls, no paper, no waiting.

Sophie is approved on the spot. She can start treating patients next Monday.

This guide shows you how to build that verification experience.

1
2
3
4
5
amsterdamumc.nl/onboardingAmsterdam UMCStaff OnboardingPositionPhysiotherapistDepartmentSports MedicineProvide BIG registration
My WalletBIG RegistrationSophie de VriesPhysiotherapistBIG: 29065432101
Sophie applies for a position at Amsterdam UMC

How It Works​

When verifying a credential from a personal wallet, the flow involves three parties: the hospital's application (where the verification is initiated), the hospital's backend (which orchestrates the process), and the hospital's Credenco Business Wallet (which creates the verification request and validates the credential).

The credential holder stays in full control — they choose exactly which credentials to share and can deny requests they don't trust.

Key Concepts

ConceptDescription
Verifier TemplateA configuration in the Credenco Business Wallet that defines which credentials you want to request from a holder
Authorization RequestAn OID4VP request that initiates the credential verification flow
QR CodePresented to the user so they can scan it with their wallet app and share credentials
OpenID4VPThe open standard protocol used for credential presentation and verification
Correlation IDA business key to track the verification session and retrieve results

Sequence Diagram​

The diagram below shows the complete interaction between all parties — from the moment the hospital requests Sophie's BIG credential to the moment her qualifications are verified.

Step-by-Step Integration​

Prerequisites​

Before you begin, make sure you have:

Step 1: Create a Verification Request​

When a user triggers credential verification (e.g., clicking "Verify credentials" during onboarding), the hospital backend calls the Create authorization request API.

Request:

curl -X POST https://your-wallet.credenco.com/api/v1/oid4vp/backend/auth/requests \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "correlation_id": "onboarding-sophie-2026",
    "query_id": "verify_big_registration",
    "qr_code": {
      "size": 400
    }
  }'

Tip: The query_id must match the Verifier template key configured in the Credenco Business Wallet. This template defines which credential types and attributes you want to verify.

Response:

{
  "correlation_id": "onboarding-sophie-2026",
  "auth_request_uri": "openid4vp://authorize?request_uri=https://your-wallet.credenco.com/oid4vp/auth/request/abc123",
  "status_uri": "https://your-wallet.credenco.com/api/v1/oid4vp/backend/auth/requests/onboarding-sophie-2026",
  "qr_uri": "data:image/png;base64,iVBORw0KGgo..."
}
FieldDescription
correlation_idYour business key to track this verification session
auth_request_uriThe OpenID4VP authorization request URI (encoded in the QR code)
status_uriEndpoint to poll for verification status
qr_uriBase64-encoded PNG image of the QR code — ready to display

Step 2: Display the QR Code​

Display the qr_uri directly in your frontend. The user needs to scan it with their wallet app:

<div style="text-align: center; padding: 2rem;">
  <h2>Verify your BIG registration</h2>
  <img src="data:image/png;base64,iVBORw0KGgo..." alt="Verification QR Code" />
  <p>Open your wallet app and scan the code to share your BIG credential.</p>
</div>

Note: The QR code is single-use. Each verification session requires a new QR code.

Step 3: The User Shares Their Credential​

From Sophie's perspective:

  1. Sophie opens her personal wallet app on her phone
  2. She taps "Scan QR code"
  3. The wallet app reads the QR code and contacts the hospital's Credenco Business Wallet
  4. The wallet shows which credentials Amsterdam UMC is requesting — her BIG registration
  5. Sophie reviews the request and taps "Share"
  6. The wallet sends the credential to the hospital's Credenco Business Wallet using the OpenID4VP protocol
  7. The hospital's Business Wallet cryptographically verifies the signature and checks the credential's validity

Sophie stays in full control — she sees exactly what is being requested and can deny the request at any time.

Step 4: Check the Verification Status​

After the QR code is displayed, your backend polls the Get authorization session status API to track progress and retrieve results:

curl "https://your-wallet.credenco.com/api/v1/oid4vp/backend/auth/requests/onboarding-sophie-2026?includeData=true" \
  -H "x-api-key: YOUR_API_KEY"

Response (after credential is verified):

{
  "status": "verified",
  "correlation_id": "onboarding-sophie-2026",
  "last_updated": 1751155200000,
  "data": {
    "first_name": "Sophie",
    "last_name": "de Vries",
    "big_number": "29065432101",
    "profession": "Physiotherapist",
    "specialism": "Sports Physiotherapy",
    "registration_date": "2026-03-19",
    "valid_until": "2031-03-19"
  }
}
StatusMeaning
createdThe authorization request has been created, waiting for the wallet to respond
request_retrievedThe wallet app has retrieved the authorization request
verifiedThe credential has been successfully presented and verified
errorSomething went wrong during the verification process

Tip: Use the includeData=true query parameter to include the actual credential data in the response. Without it, you only get the status.

Optional: Use Callbacks Instead of Polling​

Instead of polling, provide a callback URL in the verification request:

{
  "correlation_id": "onboarding-sophie-2026",
  "query_id": "verify_big_registration",
  "qr_code": { "size": 400 },
  "callback": {
    "url": "https://your-backend.com/webhooks/verification-status",
    "status": ["verified", "error"]
  }
}

Your callback endpoint will receive a POST request when the verification completes or fails.

Complete Flow at a Glance​

1
Hospital Backend
Calls the Verification API and requests a QR code

2
Show QR Code
Display the QR code in the hospital's onboarding portal

3
Sophie Shares
She scans the QR code and approves sharing her BIG credential

4
Instantly Verified
The hospital's Business Wallet verifies the credential — onboarding is approved

API Reference​

APIMethodEndpointDescription
Create authorization requestPOST/api/v1/oid4vp/backend/auth/requestsCreate a verification request and get a QR code
Get authorization session statusGET/api/v1/oid4vp/backend/auth/requests/{correlationId}Check verification status and retrieve credential data

What's Next?​

Now that you understand how to verify credentials from a personal wallet, you might want to explore: