Skip to main content
Blog
Home/

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

Author Ivan Dinkov
Ivan DinkovSr. Developer Support Advisory Engineer
Summary3 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

    Table of contents

    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" 
        })
    
    

    As you can see, creating a hyperlink through the API involves few steps and is very easy.

    Additional resources

    Author Ivan Dinkov
    Ivan DinkovSr. Developer Support Advisory Engineer
    More posts from this author

    Related posts

    • From the Trenches: How to fix missing Docusign email notifications for recipients
      Developer Support Articles

      From the Trenches: How to fix missing Docusign email notifications for recipients

      Author Byungjae Chung
      Byungjae Chung
    • Meet the winners of Docusign Hackathon: Unlocked

      Meet the winners of Docusign Hackathon: Unlocked

      Author Nikhil Patel
      Nikhil Patel
    • How to fix duplicate tabs in Docusign: Anchor vs. custom tabs

      How to fix duplicate tabs in Docusign: Anchor vs. custom tabs

      Author Sai Dandamudi
      Sai Dandamudi
    Meet the winners of Docusign Hackathon: Unlocked

    Meet the winners of Docusign Hackathon: Unlocked

    Author Nikhil Patel
    Nikhil Patel
    How to fix duplicate tabs in Docusign: Anchor vs. custom tabs

    How to fix duplicate tabs in Docusign: Anchor vs. custom tabs

    Author Sai Dandamudi
    Sai Dandamudi

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting