Registered wallet queries

Ask a person's swiyu wallet for a secuveri credential through the secuveri API. A wallet shows "This request has not been registered" unless the request is registered with the secuveri trust root. A registered request carries a signed verification-query public statement (vqPS), and the wallet shows your purpose instead. You register a query once, then create requests for it by its scope.

1. Request the registration

In Settings, under Verification queries, owners and admins enter a name, the secuveri credential (secuveri Verified Passport or secuveri KYC Attestation), the claims you need and the purpose shown in the wallet. The purpose name (at most 40 characters) and description (at most 1000) need a default text and may add German, French, Italian and English. The scope becomes org.<your organization>.<name>. secuveri checks every request: only secuveri's own credential types, only claims those types carry, each claim named explicitly (no wildcards, no request for every claim).

secuveri reviews the request. Once it is approved, the trust root signs it at the next trust sync, at the latest within a day; the tab then shows it as Registered. To change a query, withdraw it and request it again. A withdrawn or revoked query is dropped at the next sync, and a verifier that already cached its vqPS keeps it until the vqPS expires (up to 180 days).

2. Create a wallet request

With an API key that may create sessions (sessions:write), send the scope of a registered query. secuveri creates the request on its verifier with exactly the registered DCQL query and purpose; you never send the query yourself. Only your organization's registered (approved) queries work. A scope that is still in review, rejected, withdrawn, revoked or another organization's gets a 404. At most 60 calls a minute.

curl
curl -X POST https://api-verify.secuveri.com/v1/wallet-requests \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scope":"org.acme.onboarding"}'
JSON
{
  "id": "3f0c9a8e-1b2d-4c5e-8f70-9a1b2c3d4e5f",
  "scope": "org.acme.onboarding",
  "status": "pending",
  "deeplink": "https://wallet.secuveri.com/verify?client_id=…&request_uri=…",
  "qr_url": "https://verify.secuveri.com/wallet-request?d=https%3A%2F%2Fwallet.secuveri.com%2Fverify%3F…",
  "created_at": "2026-11-19T12:00:00.000Z"
}

On a phone, open deeplink (a button that starts the wallet). On a computer, show the page at qr_url, which displays the request as a secuveri QR code, or draw your own QR code from deeplink.

3. Read the outcome

Poll GET /v1/wallet-requests/{id} with a key that may read results (results:read) until status is success or failed. claims holds what the person disclosed, only once the wallet answered and only for your organization's own requests. secuveri does not keep the disclosed claims; read them while the verifier still holds the request (expired afterwards). Each read of disclosed claims is recorded in your organization's audit log.

JSON
{
  "id": "3f0c9a8e-1b2d-4c5e-8f70-9a1b2c3d4e5f",
  "scope": "org.acme.onboarding",
  "status": "success",
  "claims": {
    "given_name": "Anna",
    "family_name": "Muster",
    "birth_date": "1990-04-12"
  },
  "error": null
}