Skip to main content

Send verification links

note

This article explains how to call the API to create verification links. For a general introduction into what verification links are, read this article.

This article uses us-east to illustrate examples. Replace it with your own region code.

To create a verification link, authenticate using your API credentials as described in the Authentication guide.

Then, send a POST request (application/json) to your endpoint, for example:

curl --url https://api.us-east.platform.microblink.com/agent/api/v1/verification-link --user "$CLIENT_ID:$CLIENT_SECRET" --json @request_body.json

There are several required and optional parameters which can be provided to modify the behavior of the link:

request_body.json
{
  "expiresOn": "2025-03-04T22:33:44.555Z",  // required
  "workflowId": "66d99fa9edc165df54072f8a", // required
  "runAddress": "your.run.address",         // optional
  "formValues": {                           // optional
    "key1": "value1",
    "key2": "value2",
  },
  "props": {                                // optional
    "foo": "value"
   },
  "redirectUrl": "https://example.com",     // optional
  "consent": {
    "userId": "example",                    // required
    "note": "example",                      // optional
    "givenOn": "2025-03-04T22:33:44.555Z",  // optional
    "isProcessingStoringAllowed": true,     // optional
    "isTrainingAllowed": true               // optional
  }
}
  • runAddress: Application which is used to execute the transaction created by the link. When it's not provided, the default Microblink-provided application is used (https://platform.microblink.com/run).
  • formValues: If the workflow has defined input parameters, define values here.
  • props: Custom key-value collection to be stored within the transaction. Not used by the platform.
  • consent: Read more in Get users' consent.

Response​

If the request was successful, the API returns this object:

{
  "id": "0266d99fa9edc165df54072f8b",
  "address": "https://api.us-east.platform.microblink.com/edge/api/v1/verification-link/0266d99fa9edc165df54072f8b"
}

The value in the address field is the verification link. Send this link to your users.

sdk query parameter​

When the API endpoint processes the verification link and redirects the user to the second address (runAddress—the address of the application which performs the actual scan of the identity document), it also appends base64-encoded data under the sdk query parameter.

This data must be sent to initialize the processing app, as well as to enable resuming communication with the back end after processing the identity document.

Decoded, the data looks like this:

{
  "source": "VerificationLink",
  "apiAddress": "https://api.us-east.platform.microblink.com/edge",
  "transactionId": "02680fa7048e752353efbdf975",
  "ephemeralKey": "9KBU+04q_Nn7soaHR+MTNFL43C7b5b_4N2P25LLDTlWl06k3NfWJd+6fmwyFnzJ-",
  "redirectUrl": null,
  "verificationLinkId": "02680fa6f73c487e1d7706cc6a",
  "deviceJoinKey": null,
  "deviceJoinKeyExpiresOn": null
}

If you are self-hosting the app that will run the verification link, read the Run address article to understand how your web SDK needs to be configured to accept this data.

Last updated on