Skip to main content

Compound proof requests

A compound proof request lets an organization ask for multiple credentials in one verification journey. The organization can require every credential, accept one of several alternatives, or combine both rules.

For example, a service may require:

Proof of identity and either a driving licence or a passport.

Without a compound request, these checks may require separate verification journeys. A compound request presents them to the holder as one request and creates one proof exchange for the verifier to track.

How compound verification works​

Verifier creates one proof request
↓
Holder wallet finds matching credentials
↓
Holder reviews and selects credentials
↓
Holder wallet submits one presentation
↓
Verifier retrieves the verification result
  • Verifier: Uses the Hovi Connect API to create the request and retrieve its result.
  • Holder: Responds through either an organizational wallet (Hovi Connect API) or the Cloud Wallet API.

Before you start​

You need:

  • An EU Digital Identity API key for Hovi Connect API and organizational wallet requests.
  • The appropriate organization ID, sent in the x-organization-id header.
  • A wallet access token when using the Cloud Wallet API.
  • One verification template for each type of credential the verifier may request.
  • Matching credentials in the holder wallet to complete the examples.

The IDs in this guide are examples. Replace them with IDs from your ecosystem.

CredentialVerification template IDFormat
Identity419333f3-7f4f-419c-b8a5-0ff3941c95d5dc+sd-jwt
Driving licence4a0c9778-8b74-4186-96ee-7b772d82ad0bmso_mdoc
Passporte78321b2-32cf-4eb1-9c76-fcb7cc706ea4dc+sd-jwt

Describe the credentials you need​

Send compound requests to POST /verification/send-proof-request. Instead of supplying one verificationTemplateId, use credentialQueries to describe the credentials.

Each query contains:

  • id: A name that identifies the query throughout the request.
  • verificationTemplateId: The template that defines the credential and claims to match.

Query IDs are case-sensitive. They must be unique within the request and contain 1–128 letters, numbers, underscores, or hyphens.

The following request requires both identity and driving-licence credentials:

{
"credentialQueries": [
{
"id": "identity",
"verificationTemplateId": "419333f3-7f4f-419c-b8a5-0ff3941c95d5"
},
{
"id": "licence",
"verificationTemplateId": "4a0c9778-8b74-4186-96ee-7b772d82ad0b"
}
]
}

When credentialRequirement is omitted, every query is required.

Choose how the requirements work together​

The optional credentialRequirement object controls which credential queries the holder must satisfy.

ModeMeaningExample
allEvery query is requiredIdentity and licence
anyOne query is requiredLicence or passport
groupEvery group is required, while each group applies its own all or any ruleIdentity and (licence or passport)

Omitting credentialRequirement has the same effect as { "mode": "all" }.

Require all credentials​

Use all when the holder must satisfy every query:

"credentialRequirement": {
"mode": "all"
}

Accept any credential​

Use any when one query is sufficient:

"credentialRequirement": {
"mode": "any"
}

For example, queries for a licence and passport with mode: "any" allow the holder to present either credential.

Combine mandatory credentials with alternatives​

Use group for a requirement such as identity and either a driving licence or a passport:

{
"credentialQueries": [
{
"id": "identity",
"verificationTemplateId": "419333f3-7f4f-419c-b8a5-0ff3941c95d5"
},
{
"id": "licence",
"verificationTemplateId": "4a0c9778-8b74-4186-96ee-7b772d82ad0b"
},
{
"id": "passport",
"verificationTemplateId": "e78321b2-32cf-4eb1-9c76-fcb7cc706ea4"
}
],
"credentialRequirement": {
"mode": "group",
"groups": [
{
"mode": "all",
"queryIds": ["identity"]
},
{
"mode": "any",
"queryIds": ["licence", "passport"]
}
]
}
}

Every group is mandatory. An all group requires every query listed in queryIds; an any group requires one listed query. Every credential query must belong to exactly one group.

Holder selectionResult
Identity and licenceAccepted
Identity and passportAccepted
Identity onlyRejected because the alternative group is incomplete
Licence onlyRejected because identity is missing
Identity, licence, and passportRejected for explicit selection because only one any alternative may be selected

Supported credential formats​

Compound requests are available only in the EU Digital Identity ecosystem. They support:

  • dc+sd-jwt
  • mso_mdoc
  • A mixture of both formats in one request

The grouped example above is mixed-format: identity and passport use dc+sd-jwt, while the driving licence uses mso_mdoc.

The compound request form does not support vc+sd-jwt, JSON-LD, JWT, or AnonCreds. Those formats retain their existing single-template behavior.

Each verification template must belong to the current ecosystem, be accessible to the API key, and reference a compatible credential template when one is linked.

Verifier: create the request​

Send the grouped request to POST /verification/send-proof-request.

Authenticate with the ecosystem API key and send the verifier organization ID in x-organization-id.

A successful request returns one proof exchange:

{
"success": true,
"response": {
"proofExchangeId": "0a6af7f2-02af-41f5-b97d-8e0195519836",
"verificationUri": "openid4vp://?client_id=...&request_uri=...",
"verificationUrl": "https://studio.hovi.id/verification?data=..."
}
}

Share verificationUri or verificationUrl with the holder. Store proofExchangeId so the verifier can retrieve the status and result.

Creating a compound request counts as one verification session, regardless of how many credential queries it contains.

Holder: choose a wallet API​

Both holder wallet options apply the same matching and selection rules. Their endpoints and authentication differ.

Organizational wallet​

Cloud Wallet API​

Holder: preview matching credentials​

Preview the request before submitting so the holder can review the available credentials and requirements.

Organizational wallet request:

{
"proofRequestUri": "openid4vp://?client_id=...&request_uri=..."
}

Cloud Wallet API request:

{
"protocol": "openid",
"proofRequestUri": "openid4vp://?client_id=...&request_uri=..."
}

Both APIs return credentialsByQueryId and credentialRequirements. The following excerpt shows the compound-proof-specific fields:

{
"credentialsByQueryId": {
"identity": [
{
"credentialId": "5362a21e-9aec-4f9b-b66e-fdfb96a70294",
"credentialType": "dc+sd-jwt"
}
],
"licence": [
{
"credentialId": "9bc4c4db-1f05-47d2-892a-3471862f1e01",
"credentialType": "mso_mdoc"
}
],
"passport": []
},
"credentialRequirements": [
{
"required": true,
"mode": "all",
"queryIds": ["identity"]
},
{
"required": true,
"mode": "any",
"queryIds": ["licence", "passport"]
}
]
}

The existing flat credentials collection remains available. credentialsByQueryId shows which stored credentials can satisfy each query. A query with no match has an empty array.

In this example, the wallet has no matching passport, but the request can still be completed with identity and licence.

Holder: select and submit credentials​

Use selectedCredentials when the holder needs to choose between matching credentials or alternatives:

"selectedCredentials": [
{
"id": "identity",
"credentialId": "5362a21e-9aec-4f9b-b66e-fdfb96a70294"
},
{
"id": "licence",
"credentialId": "9bc4c4db-1f05-47d2-892a-3471862f1e01"
}
]

In each selection:

  • id is a query ID from credentialsByQueryId.
  • credentialId is a matching credential listed for that query.

Select at most one credential for each query. An all requirement needs a credential for every query; an any requirement needs one alternative.

Organizational wallet submission​

{
"proofRequestUri": "openid4vp://?client_id=...&request_uri=...",
"selectedCredentials": [
{ "id": "identity", "credentialId": "5362a21e-9aec-4f9b-b66e-fdfb96a70294" },
{ "id": "licence", "credentialId": "9bc4c4db-1f05-47d2-892a-3471862f1e01" }
]
}

Cloud Wallet API submission​

{
"protocol": "openid",
"proofRequestUri": "openid4vp://?client_id=...&request_uri=...",
"selectedCredentials": [
{ "id": "identity", "credentialId": "5362a21e-9aec-4f9b-b66e-fdfb96a70294" },
{ "id": "licence", "credentialId": "9bc4c4db-1f05-47d2-892a-3471862f1e01" }
]
}

The holder may omit both credentialId and selectedCredentials to use automatic credential selection. Explicit selections must satisfy the entire request; missing required queries are not added automatically.

Verifier: retrieve the result​

Retrieve the request using the proofExchangeId returned at creation through GET /verification/proof-request/find. Pass the ID in the proofExchangeId query parameter.

Authenticate with the ecosystem API key and send the verifier organization ID in x-organization-id.

A completed request has state: "done" and isVerified: true. Its presentation associates the submitted credentials with the original query IDs. The verifier can also receive the EU Digital Identity presentation-verification webhook when verification completes.

See the verification webhook API reference for the complete webhook schema.

Common problems​

  • Both request forms were supplied. Use either verificationTemplateId for the existing single-template flow or credentialQueries for the compound flow, never both.
  • A query ID is invalid or repeated. Use a unique, case-sensitive ID containing only letters, numbers, underscores, or hyphens.
  • A group is incomplete. With mode: "group", every query must belong to exactly one group.
  • A template cannot be used. Confirm that it is accessible in the current ecosystem and uses dc+sd-jwt or mso_mdoc.
  • The selected credentials are incomplete. Satisfy every all group and choose one query from every any group.
  • A credential does not match its query. Choose a credentialId listed under that query in credentialsByQueryId.
  • Both selection forms were supplied. Use either the legacy credentialId field or selectedCredentials, never both.
  • No matching credentials are available. A successfully evaluated query returns an empty array. In the Cloud Wallet API, failure to load matching information instead returns HTTP 502 with Unable to load matching credentials for this proof request.

See the relevant API reference for complete validation messages and HTTP response schemas.

Backward compatibility​

Compound proof requests add a new request form without replacing existing behavior:

  • Existing single-template requests continue to use verificationTemplateId.
  • Existing JSON-LD and vc+sd-jwt single-template requests continue to work.
  • Existing holder submissions using credentialId continue to work for a credential-query request containing exactly one query and for Presentation Exchange requests.
  • Omitting credential selection continues to use automatic selection.
  • A successful compound request still creates one proof exchange and returns one proofExchangeId, verificationUri, and verificationUrl.

Current limitations​

  • Compound requests support only dc+sd-jwt and mso_mdoc in the EU Digital Identity ecosystem.
  • Groups cannot be nested, and every verifier-defined group is mandatory.
  • A group may require all its queries or any one query. Alternative bundles such as (identity AND licence) OR passport are not supported.
  • The holder does not support a required credential set whose alternatives contain different multi-credential combinations.
  • Explicit holder selection supports at most one stored credential per query.