From the Trenches: Creating hyperlinks through the API with the Apex Toolkit

Ivan DinkovSr. Developer Support Advisory Engineer

•Published Apr 5, 2024

Summary•3 min read

Use the eSignature REST API and Apex Toolkit to add hyperlinks to your envelopes.

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

A hyperlink does not exist as a separate tab in Docusign. Instead, users have to create a custom text tab as a Document Custom Field with specified properties. What makes the text tab an actual hyperlink is the addition of #HREF_ in the name. This guide consisting of a few steps explains how it's done through Settings > Document Custom Field.

The problem developers often face is when it comes to converting the steps from guides like this into code and mapping the values to the correct properties. In this case, it’s not that complicated: To create a hyperlink with the API, you simply create a text tab, add a few properties, and assign it to the recipient. Let's look at how this is done using the Apex Toolkit.

The code snippet below shows a sample hyperlink to Google. Of course, the link can be any link you need your customers to visit. For example, the link may be to a single document or a page on your website the signer can view before signing the document.

Note: For the hyperlink to work in Apex, properties must be in the exact order as shown below.

dfsle.Tab hyperlinkTab = new dfsle.TextTab()
    .withValue('Go to Google')
    .withReadOnly(true)
    .withRequired(true)
    .withDataLabel('#HREF_Google')
    .withTooltip('https://www.google.com')
    .withName('https://www.google.com')
    .withPosition(new dfsle.Tab.Position(
        1,
        1,
        50,
        50,
        null,
        null));

Next, add the new text tab to the list of tabs assigned to the recipient.

myRecipient = myRecipient.withTabs(new List<dfsle.Tab> { 
        myTextTab
 });

When creating the envelopes from JSON, the structure of the text tab will be similar, but will follow the eSignature JSON naming convention.

"textTabs": [
    {
        "name": "https://www.google.com",
        "value": "Go to Google",
        "required": "true",
        "locked": "true",
        "tabLabel": "#HREF_Google",
        "documentId": "1",
        "recipientId": "1",
        "pageNumber": "1",
        "xPosition": "100",
        "yPosition": "100",
        "tabType": "text",
        "tooltip": "https://www.google.com"
    }
]

Here's how to create the tab in each of our SDKs.

C#

Text hyperlinkTab = new Text
{
	DocumentId = "1",  
	Locked = "true",  
	Name = "https://www.google.com",  
	PageNumber = "1",  
	RecipientId = "1",  
	Required = "true",  
	TabLabel = "#HREF_Google",  
	TabType = "text",  
	Tooltip = "https://www.google.com",  
	Value = "Go to Google",  
	XPosition = "100",  
	YPosition = "100" 
};

Java

Text hyperlinkTab = new Text();
hyperlinkTab.setDocumentId("1");  
hyperlinkTab.setLocked("true");  
hyperlinkTab.setName("https://www.google.com");  
hyperlinkTab.setPageNumber("1");  
hyperlinkTab.setRecipientId("1");  
hyperlinkTab.setRequired("true");  
hyperlinkTab.setTabLabel("#HREF_Google");  
hyperlinkTab.setTabType("text");  
hyperlinkTab.setTooltip("https://www.google.com");  
hyperlinkTab.setValue("Go to Google");  
hyperlinkTab.setXPosition("100");  
hyperlinkTab.setYPosition("100");

Node.js

let hyperlinkTab  = docusign.Text.constructFromObject({
    documentId: "1",  
    locked: "true",  
    name: "https://www.google.com",  
    pageNumber: "1",  
    recipientId: "1",  
    required: "true",  
    tabLabel: "#HREF_Google",  
    tabType: "text",  
    tooltip: "https://www.google.com",  
    value: "Go to Google",  
    xPosition: "100",  
    yPosition: "100" 
    });

PHP

$text_tab_hyperlink = new \Docusign\eSign\Model\Text([
    'document_id' => "1",  
    'locked' => "true",  
    'name' => "https://www.google.com",  
    'page_number' => "1",  
    'recipient_id' => "1",  
    'required' => "true",  
    'tab_label' => "#HREF_Google",  
    'tab_type' => "text",  
    'tooltip' => "https://www.google.com",  
    'value' => "Go to Google",  
    'x_position' => "100",  
    'y_position' => "100" 
    ]);

Python

text_tab_hyperlink = docusign.Text(
    document_id = "1",  
    locked = "true",  
    name = "https://www.google.com",  
    page_number = "1",  
    recipient_id = "1",  
    required = "true",  
    tab_label = "#HREF_Google",  
    tab_type = "text",  
    tooltip = "https://www.google.com",  
    value = "Go to Google",  
    x_position = "100",  
    y_position = "100" 
    )

Ruby

text_tab_hyperlink = DocuSign_eSign::Text.new({
    :documentId => "1",  
    :locked => "true",  
    :name => "https://www.google.com",  
    :pageNumber => "1",  
    :recipientId => "1",  
    :required => "true",  
    :tabLabel => "#HREF_Google",  
    :tabType => "text",  
    :tooltip => "https://www.google.com",  
    :value => "Go to Google",  
    :xPosition => "100",  
    :yPosition => "100" 
    })