/v1/verifier/requests
API Key
Create a presentation request
Create a new OpenID4VP presentation request. The request defines what credentials
and claims the verifier wants from a holder. Supports both Presentation Exchange
and DCQL query formats.
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
X-API-Key
*
|
header | string | Verifier API key for authentication |
* Required parameter
Request Body
Parameters for creating a presentation request
name
*
string
Display name for the request
Example: Age Verification
purpose
string
Purpose shown to holder explaining why claims are needed
Example: We need to verify you are over 21 to complete this purchase
query_format
string
Query format to use (default: dcql)
Allowed values: "presentation_exchange", "dcql"
Example: presentation_exchange
dcql_query
object
DCQL query definition (for dcql format)
Example: {"credentials":[{"id":"age_cred","format":"vc+sd-jwt","claims":[{"path":["birthDate"]}]}]}
presentation_definition
object
Presentation Exchange definition (for presentation_exchange format)
Example: {"id":"age_verification_request","input_descriptors":[{"id":"age_credential","name":"Age Verification","purpose":"Verify you are over 21","constraints":{"fields":[{"path":["$.credentialSubject.birthDate"]}]}}]}
expires_in
integer
Expiration in seconds from now
Example: 86400
max_responses
integer
Maximum number of responses allowed
Example: 1
callback_url
string (uri)
Webhook URL for response notifications
Example: https://example.com/webhooks/presentations
redirect_url
string (uri)
Where to redirect holder after response
Example: https://example.com/verification-complete
Response
Content-Type: application/json
success
boolean
data
object
An OpenID4VP presentation request created by a verifier
uuid
*
string (uuid)
Unique identifier for the presentation request
Example: 4f0769f1-d7be-429e-a316-d28ff0cae1b6
name
*
string
Display name for the request
Example: Age Verification
purpose
string
nullable
Purpose shown to holder explaining why claims are needed
Example: Verify you are over 21 to purchase alcohol
status
*
string
Current status of the request: - draft: Not yet activated - active: Accepting responses - expired: Past expiration time - closed: Manually closed by verifier
Allowed values: "draft", "active", "expired", "closed"
Example: active
query_format
*
string
Query format used: - dcql: Digital Credentials Query Language (OpenID4VP native) - presentation_exchange: DIF Presentation Exchange format
Allowed values: "presentation_exchange", "dcql"
Example: presentation_exchange
expires_at
string (date-time)
nullable
When the request expires
Example: 2025-01-16T23:59:59Z
max_responses
integer
nullable
Maximum number of responses allowed (null = unlimited)
Example: 1
callback_url
string (uri)
nullable
Webhook URL for response notifications
Example: https://example.com/webhooks/presentation
redirect_url
string (uri)
nullable
Where to redirect holder after response
Example: https://example.com/verification-complete
created_at
*
string (date-time)
When the request was created
Example: 2025-01-15T10:00:00Z
updated_at
*
string (date-time)
When the request was last updated
Example: 2025-01-15T10:00:00Z
verifier
*
object
The verifier organization
name
string
Organization name
Example: Acme Bar & Grill
domain
string
nullable
Verified domain
Example: acme-bar.com
urls
object
nullable
URLs for accessing/sharing the request (included on show)
dashboard_url
string (uri)
Human-viewable dashboard URL
Example: https://aho.com/verify/a1cc92eb-839d-4ab8-a843-d6c0fea6d68a
openid4vp_uri
string
Wallet deep link (openid4vp://...)
Example: openid4vp://authorize?request_uri=https%3A%2F%2F...
request_uri
string (uri)
Raw JAR endpoint URL
Example: https://aho.com/openid4vp/requests/beef8d2e-61bd-4564-8a3b-5a211aafc1d0
qr_code_data
string
Data for QR code generation
Example: openid4vp://authorize?request_uri=...
stats
object
nullable
Response statistics (included on show)
response_count
integer
Total responses received
Example: 5
approved_count
integer
Approved responses
Example: 4
pending_count
integer
Pending responses
Example: 1
dcql_query
object
nullable
DCQL query definition (only for dcql format)
credentials
array[object]
Array items:
credential_sets
array[object]
nullable
Array items:
presentation_definition
object
nullable
Presentation Exchange definition (only for presentation_exchange format)
input_descriptors
array[object]
Array items:
Code Examples
import os
from aho_sdk import AhoSdk
client = AhoSdk.verifier(api_key=os.environ["AHO_API_KEY"])
result = client.requests.create(
body={
"name": "Age Verification",
"purpose": "We need to verify you are over 21 to complete this purchase",
"query_format": "presentation_exchange",
"dcql_query": {
"credentials": [{
"id": "age_cred",
"format": "vc+sd-jwt",
"claims": [{
"path": ["birthDate"]
}]
}]
},
"presentation_definition": {
"id": "age_verification_request",
"input_descriptors": [{
"id": "age_credential",
"name": "Age Verification",
"purpose": "Verify you are over 21",
"constraints": {
"fields": [{
"path": ["$.credentialSubject.birthDate"]
}]
}
}]
},
"expires_in": 86400,
"max_responses": 1,
"callback_url": "https://example.com/webhooks/presentations",
"redirect_url": "https://example.com/verification-complete"
}
)client = AhoSdk.verifier(api_key: ENV["AHO_API_KEY"])
result = client.requests.create(
body: {
name: "Age Verification",
purpose: "We need to verify you are over 21 to complete this purchase",
query_format: "presentation_exchange",
dcql_query: {
credentials: [{
id: "age_cred",
format: "vc+sd-jwt",
claims: [{
path: ["birthDate"]
}]
}]
},
presentation_definition: {
id: "age_verification_request",
input_descriptors: [{
id: "age_credential",
name: "Age Verification",
purpose: "Verify you are over 21",
constraints: {
fields: [{
path: ["$.credentialSubject.birthDate"]
}]
}
}]
},
expires_in: 86400,
max_responses: 1,
callback_url: "https://example.com/webhooks/presentations",
redirect_url: "https://example.com/verification-complete"
}
)import { AhoSdk } from '@aho/sdk';
const client = AhoSdk.verifier({ apiKey: process.env.AHO_API_KEY });
const result = await client.requests.create({
body: {
name: "Age Verification",
purpose: "We need to verify you are over 21 to complete this purchase",
queryFormat: "presentation_exchange",
dcqlQuery: {
credentials: [{
id: "age_cred",
format: "vc+sd-jwt",
claims: [{
path: ["birthDate"]
}]
}]
},
presentationDefinition: {
id: "age_verification_request",
inputDescriptors: [{
id: "age_credential",
name: "Age Verification",
purpose: "Verify you are over 21",
constraints: {
fields: [{
path: ["$.credentialSubject.birthDate"]
}]
}
}]
},
expiresIn: 86400,
maxResponses: 1,
callbackUrl: "https://example.com/webhooks/presentations",
redirectUrl: "https://example.com/verification-complete"
}
});curl -X POST 'https://api.aho.com/v1/verifier/requests' \
-H 'X-API-Key: $AHO_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Age Verification",
"purpose": "We need to verify you are over 21 to complete this purchase",
"query_format": "presentation_exchange",
"dcql_query": {
"credentials": [
{
"id": "age_cred",
"format": "vc+sd-jwt",
"claims": [
{
"path": [
"birthDate"
]
}
]
}
]
},
"presentation_definition": {
"id": "age_verification_request",
"input_descriptors": [
{
"id": "age_credential",
"name": "Age Verification",
"purpose": "Verify you are over 21",
"constraints": {
"fields": [
{
"path": [
"$.credentialSubject.birthDate"
]
}
]
}
}
]
},
"expires_in": 86400,
"max_responses": 1,
"callback_url": "https://example.com/webhooks/presentations",
"redirect_url": "https://example.com/verification-complete"
}'Try It
Log in to test this endpoint directly from the documentation.
Log in