Create a presentation request

Overview

Once you’ve picked a preset (see Browse presentation presets), create the request by passing its id. The response carries the URIs you’ll deliver to the user. This guide uses didx:basic-identity-request, which asks for firstName and lastName from a basic identity credential, accepting issuers such as the South African Reserve Bank and the Department of Home Affairs.

Need to verify something no preset covers? See Custom presentation template. For everything else, use a preset.

Endpoint

POST $BASE_URL/me-creds/api/v1/presentations/request

Request

curl -X POST "$BASE_URL/me-creds/api/v1/presentations/request" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "presetId:didx:basic-identity-request"
  }'

Request body

Field	Type	Description
`reference`	string	What to ask for, as `KIND:VALUE`. See the reference kinds below.

Reference kinds

reference splits on the first colon only, so the value may itself contain colons, as preset ids do.

Kind	Example	Resolves to
`presetId`	`presetId:didx:basic-identity-request`	The presentation preset. Browse them at `GET /v1/presets/presentations`. The usual choice.
`templateId`	`templateId:cm2ytsdid009u4ke3t30aiuvc`	That presentation template directly. For custom shapes.

Unlike issuance, presentation requests do not accept the credentialType kind.

The older top-level presetId and presentationTemplateId fields still work but are deprecated. Pass exactly one of reference, presetId, or presentationTemplateId. Supplying more than one returns a 400. New integrations should use reference.

Response

HTTP 200 OK

{
  "data": {
    "id": "cmbhsgi6c00cls60120oyb8tl",
    "createdAt": "2025-06-04T10:12:20.101Z",
    "updatedAt": "2025-06-04T10:12:20.101Z",
    "status": "requested",
    "error": null,
    "expiresAt": "2025-06-04T10:27:20.088Z",
    "authorizationRequestUri": "https://creds-app.test.didxtech.com/invitation?request_uri=...",
    "authorizationRequestQrUri": "https://creds-app.test.didxtech.com/invitation?request_uri=...&qr=true"
  }
}

Key response fields

Field	Description
`id`	Unique presentation request identifier. Save this for later steps
`status`	`requested` initially. Transitions to `verified` once the user responds
`authorizationRequestUri`	Link the user can paste directly into their wallet
`authorizationRequestQrUri`	QR-optimised version for scanning with a wallet app
`expiresAt`	Request expires 15 minutes after creation

15 minutes is short. Create the request at the point you’re ready to put it in front of the user, not ahead of time. A request generated during a batch job will usually be dead before anyone scans it. You cannot revive an expired request, so create a new one.

Deliver the request

Save the id so you can read the user’s response later, then deliver the request to the user. Two options:

By email, username, or other identifier: Deliver via identifier.
As a QR code or deeplink rendered in your own UI: Deliver out of band.

Overview

User Onboarding

Issuance

Verification

Branding

Webhooks

Custom Templates (advanced)

Errors

Overview

Endpoint

Request

Request body

Reference kinds

Response

Key response fields

Deliver the request

​Overview

​Endpoint

​Request

​Request body

​Reference kinds

​Response

​Key response fields

​Deliver the request

Overview

Endpoint

Request

Request body

Reference kinds

Response

Key response fields

Deliver the request