Passing Linked Data in a Template Link Query String

You must not pass sensitive data using the LinkData parameter, as data passed in URLs is unsecured. See Sensitive Data for more information.

LinkData is an optional parameter you can add to a template link query string. Using this parameter, a template link can pass additional data to the interview and compatible webhooks.

For example, you can add an account ID from your own system to the LinkData property. When the user opens the template link, other webhooks you have created in Advance include the LinkData value with the data passed to your own web application. The web application can then use the account ID to retrieve answer data relevant to that user. In this way, you can use the LinkData property to identify users and pass user-specific answer data back to the interview.

Overview

You use the LinkData parameter to pass string data from the template link to the interview and any compatible webhooks you have configured in Advance. When you pass data to Advance using LinkData, Advance makes the data accessible to you in the following ways:

You can use the LinkData property to pass whatever string data you want to a webhook. However, a typical use case is to pass a user's account ID from the template link through a webhook to a web application endpoint. This enables you to identify which user has used the template link. Using that information, you can retrieve data specific to that user and return it to the interview as answer data.

The LinkData property allows a maximum of 100 characters.

Workflow

The following diagram demonstrates the flow of LinkData data from a template link in your own web application to an Advance interview.

Sensitive Data

You must not pass sensitive data in the URL. URLs are unsecured as they can be accessed through web server logs, browser history, referrer headers, and so on. In particular, personally identifiable information and long-term secrets (usernames, passwords, API tokens, and long-lasting access tokens) should never be sent in the query string. You should use ephemeral tokens, such as CSRF tokens, where possible.

Getting a LinkData Value in the HotDocs Interview

During the interview, you can access any LinkData value passed from a template link using the HD_UserContext_LinkData user context data variable.

LinkData Sent from Advance to your Endpoint

Advance sends LinkData to the endpoints you configure when creating custom interview event and interview load event webhooks.

Custom Interview Event

The LinkData value passed in a custom interview event is displayed in the user context data of the JSON response.

Example JSON Response Data

{
    "linkedVariable": { "ParameterValue": "Event Dialog Button" },
    "userContextData": {
        "UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc", 
        "UserFirstName": "John",
        "UserLastName": "MacDiarmid",
        "UserEmailAddress": "jm@example.com",
        ...
        "LinkData": "ExampleValue"
}

Interview Load Events

The LinkData value passed in a load interview event is displayed in both the linkedVariable's parameter value and the user context data of the JSON response.

Example JSON Response Data

{
    "linkedVariable": { "ParameterValue": "LinkData String" },
    "userContextData": {
        "UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc", 
        "UserFirstName": "John",
        "UserLastName": "MacDiarmid",
        "UserEmailAddress": "jm@example.com",
        ...
        "LinkData": "ExampleValue"
}

Common Reference Topics

Among others, the following reference topics may relate to this conceptual area: