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-idheader. - 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.
| Credential | Verification template ID | Format |
|---|---|---|
| Identity | 419333f3-7f4f-419c-b8a5-0ff3941c95d5 | dc+sd-jwt |
| Driving licence | 4a0c9778-8b74-4186-96ee-7b772d82ad0b | mso_mdoc |
| Passport | e78321b2-32cf-4eb1-9c76-fcb7cc706ea4 | dc+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.
| Mode | Meaning | Example |
|---|---|---|
all | Every query is required | Identity and licence |
any | One query is required | Licence or passport |
group | Every group is required, while each group applies its own all or any rule | Identity 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 selection | Result |
|---|---|
| Identity and licence | Accepted |
| Identity and passport | Accepted |
| Identity only | Rejected because the alternative group is incomplete |
| Licence only | Rejected because identity is missing |
| Identity, licence, and passport | Rejected 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-jwtmso_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
- Preview:
POST /wallet/verification/preview-request - Submit:
POST /wallet/verification/submit-presentation - Authentication: ecosystem API key and
x-organization-id - The request body does not require
protocol.
Cloud Wallet API
- Preview:
POST /proof/preview-request - Submit:
POST /proof/submit-presentation - Authentication: wallet access token
- Set the required API field
protocolto"openid".
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:
idis a query ID fromcredentialsByQueryId.credentialIdis 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
verificationTemplateIdfor the existing single-template flow orcredentialQueriesfor 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-jwtormso_mdoc. - The selected credentials are incomplete. Satisfy every
allgroup and choose one query from everyanygroup. - A credential does not match its query. Choose a
credentialIdlisted under that query incredentialsByQueryId. - Both selection forms were supplied. Use either the legacy
credentialIdfield orselectedCredentials, 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-jwtsingle-template requests continue to work. - Existing holder submissions using
credentialIdcontinue 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, andverificationUrl.
Current limitations
- Compound requests support only
dc+sd-jwtandmso_mdocin 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 passportare 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.