Skip to main content
Verification

Send verification request

POST/v4/config/ows/verifier/verifications

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: show requestUrl as 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: give dcApiRequest.chrome or dcApiRequest.safari to navigator.credentials.get() in the browser, then forward the result with Receive DC API verification response. requestUrl and requestObject are 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

  • Authorizationstringheaderrequired

    Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.

    Scope:verifications:request

Body

application/json

The presentation definition to use and the options of this request.

  • presentationDefinitionIdstringrequired

    The presentationDefinitionId of 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"

  • requestByReferenceboolean

    true: requestUrl has a request_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 unsigned redirect_uri request. Default false.

    Default:false

    Example:true

  • transactionDataobject

    The 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.

  • noncestring

    The nonce of 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"

  • urlPrefixstring

    The start of requestUrl, before ?. Use it to open a given wallet app, for example its universal link. Default openid4vp://.

    Example:"openid4vp://"

  • individualIdstring

    The 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.

  • mapperIdstring

    Your 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 with individualId.

  • hasSignatureStampboolean

    For a document signing request (qes_data): true puts a visible signature stamp on the signed PDF. Default false.

    Default:false

  • signatureCoordinateinteger[]

    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.

  • dataAgreementobject

    A 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 in dataAgreement.

Response

application/json

The verification history of the new request, with status request_sent.

  • verificationHistoryobject

    The 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, cryptographicKeyIdentifier and presentationDefinitionSnapshot, which are left out when they have no value. A member without a value has the empty value of its type: "" for a string, 0 for a number, false for a boolean, null for an object or an array.

    A request has no expiry flag. It expires presentationRequestLifetimeSeconds of the verifier configuration after createdAt; the verification status stream reports it as expired.