Send verification request
Sends an OpenID4VP Authorization Request from a stored presentation definition and starts a verification. The wallet takes the DCQL query, the response mode, the signing key and the transaction data template from the presentation definition (presentationDefinitionId). The answer is the verification history of the request; its presentationExchangeId is the verificationId of the other verifier operations.
How the holder gets the request depends on the responseMode of the presentation definition:
direct_post,direct_post.jwt: showrequestUrlas a QR code or open it as a deep link. The wallet fetches the request and posts its response to the verifier.dc_api,dc_api.jwt: givedcApiRequest.chromeordcApiRequest.safaritonavigator.credentials.get()in the browser, then forward the result with Receive DC API verification response.requestUrlandrequestObjectare empty.
With individualId or mapperId, the wallet also sends the request as a push notification to the device of that individual.
Follow the result with Read verification history, the verification status stream or the verifier events of a webhook (ows.verifier.verification.created, request_retrieved, presentation_received, declined). The request is valid for presentationRequestLifetimeSeconds of the verifier configuration.
Authorizations
AuthorizationstringheaderrequiredYour API key with the prefix
ApiKey:ApiKey <your-api-key>. Get an API key.Scope:
verifications:request
Body
The presentation definition to use and the options of this request.
presentationDefinition Id stringrequiredThe
presentationDefinitionIdof a presentation definition of the organisation, from List presentation definitions. Required. The request takes the DCQL query, the response mode, the signing key and the transaction data template from it.Example:
"1c3f6b1c-0c48-4b1f-9c1a-77f9c1d6a1a0"requestBy Reference booleantrue:requestUrlhas arequest_uri, and the wallet fetches the request from it, which keeps the QR code small. A signed request always goes by reference, so the value changes only an unsignedredirect_urirequest. Defaultfalse.Default:
falseExample:
truetransactionData objectThe transaction data that the holder approves with the presentation. Required when the presentation definition has a
transactionDataDefinitionType, and refused when it has none.It must follow the JSON Schema of that type (List transaction data templates). The data of an SCA type of EUDI TS12 (
payment,login_risk_transaction,account_access,emandate) is checked against the type metadata of the SCA attestation when the wallet answers.noncestringThe
nonceof the request, which the presentation must contain. Default: a new random value. Send your own only when you must bind the request to a value of your system.Example:
"z4cVLRsq9pKx0NgQ7E3hJg"urlPrefix stringThe start of
requestUrl, before?. Use it to open a given wallet app, for example its universal link. Defaultopenid4vp://.Example:
"openid4vp://"individualId stringThe ID of an individual of the organisation. The wallet also sends the request as a push notification to the device of the individual, which needs a push notification token. Do not send it with
mapperId.mapperId stringYour own ID of an individual of the organisation (the mapper ID). As
individualId, but the individual is found by this ID. Do not send it withindividualId.hasSignature Stamp booleanFor a document signing request (
qes_data):trueputs a visible signature stamp on the signed PDF. Defaultfalse.Default:
falsesignatureCoordinate integer[]For a document signing request: where the signature goes on the PDF page, as
[x1, y1, x2, y2]in points. Exactly four integers.4 items.
dataAgreement objectA data agreement whose terms the holder sees with the request. The wallet adds it to the request as
data_agreement(not to a DC API request), and the verification history keeps it indataAgreement.
Response
The verification history of the new request, with status request_sent.
verificationHistory objectThe verification history of one OpenID4VP verification request: the request, the response of the wallet and the result of the checks.
Each member is always in the answer, except
dcApiRequest,dcApiProtocol,cryptographicKeyFormat,cryptographicKeyIdentifierandpresentationDefinitionSnapshot, which are left out when they have no value. A member without a value has the empty value of its type:""for a string,0for a number,falsefor a boolean,nullfor an object or an array.A request has no expiry flag. It expires
presentationRequestLifetimeSecondsof the verifier configuration aftercreatedAt; the verification status stream reports it asexpired.