Creating a Proof Request

A proof request defines who is asking, what they are asking for, and how the request will be transmitted to the wallet holder.

Prerequisites

• A proof schema → Proof Schemas
• A verifier identifier → Identifiers

Required parameters

Proof schema

The proofSchemaId identifies the proof schema defining what you are requesting. The schema determines which credentials and claims the wallet will be asked to present.

Retrieve the UUID of your proof schema from GET /api/proof-schema/v1.

Verification protocol

The protocol determines how the system transmits the request to the wallet and how the wallet responds. Reference a configured instance name from the verificationProtocol object in your configuration — not the protocol type.

tip

If you have issues with your chosen protocol, check the following capabilities in your credential format and verification protocol configuration, respectively:

• proofExchangeProtocols
• didMethods (if using DIDs)

Verifier identifier

The verifier is the UUID of the identifier used to identify yourself as the verifier in the proof request.

tip

If you have issues with your chosen identifier, check the following capabilities in your credential format configuration:

• verificationIdentifierTypes
• verificationKeyAlgorithms
• verificationKeyStorages

And in your verification protocol configuration:

• verifierIdentifierTypes protocol

Optional parameters

redirectUri: A URL or deep link to send the wallet holder to after they submit a valid proof.

webhookDestinationUrl: A URL to receive event notifications for this proof request. See Webhooks.

transport: One or more transport protocol instances to use. If omitted, the system uses the highest-order available transport from the configuration. When multiple values are passed, the QR code contains both protocols and the wallet chooses which to use.

transport value	System action
Omitted	Uses highest-order transport
["HTTP"]	Uses the specified transport
["MQTT", "BLE"]	QR code contains both; wallet chooses

Supported combinations: [MQTT, BLE] for mobile, [HTTP, MQTT] for server deployments.

verifierKey: If your verifier DID has multiple keys for its authentication method, specify which to use here. If omitted, the system uses the first key listed.

isoMdlEngagement: For in-person mdoc verification over BLE, pass the engagement QR code content received from the wallet. See Verify ISO mdocs offline.

Example request

curl -L -X POST '/api/proof-request/v1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "proofSchemaId": "{{PROOF-SCHEMA-UUID}}",
  "protocol": "OPENID4VP_FINAL1_HAIP",
  "verifier": "{{VERIFIER-IDENTIFIER-UUID}}",
  "redirectUri": "https://example.com",
  "webhookDestinationUrl": "https://example.com/webhook"
}'

Response

The system responds with the UUID of the new proof request:

{
  "id": "{{PROOF-REQUEST-UUID}}"
}

Store this value for the next step.

Next step

Share the proof request with the holder → Sharing a Proof Request