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, you first need to get an access token. Access tokens are used for authentication when you create verification links.

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 --oauth2-bearer $ACCESS_TOKEN --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"
   },
  "consent": {
    "userId": "example",                    // required
  }
}
  • expiresOn: When the link expires. Uses the ISO 8601 format.
  • workflowId: Which workflow is used to produce a transaction.
  • runAddress: Application which is used to execute the transaction created by the link. When null, the default Microblink-provided application is used (https://platform.microblink.com/run). This is not production-ready: you need to self-host verification link run apps so that you can collect consent.
  • 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: This is collected, but will be overwritten when you run the app & provide actual 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.

To execute a verification link, use a GET request. No additional arguments or headers are needed. This allows the link to be used directly in HTML content, e-mail or direct messages.

When the link is executed, the API endpoint processes it and creates the transaction. It then returns a 302 redirect status code, and redirects the user to the previously defined runAddress, or the default address if one wasn't explicitly defined.

Verification links are single-use. Repeated execution of the same link will redirect to the same transaction.

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
}

See the Run address article to understand how your web SDK needs to be configured to accept this data.

Last updated on