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

    • Developers

      Select the right tab placement strategy for your Docusign integration

      Author Marty Scholes
      Marty Scholes
      Select the right tab placement strategy for your Docusign integration
    • The Agreement Trap: How Developers Can Break Free with Docusign IAM

      Author Raileen Del Rosario
      Raileen Del Rosario
      The Agreement Trap: How Developers Can Break Free with Docusign IAM
    • Secure, verify, comply: Automate identity checks with Docusign APIs

      Author Niani Byrd
      Niani Byrd
      Secure, verify, comply: Automate identity checks with Docusign APIs

    Select the right tab placement strategy for your Docusign integration

    Author Marty Scholes
    Marty Scholes
    Select the right tab placement strategy for your Docusign integration

    The Agreement Trap: How Developers Can Break Free with Docusign IAM

    Author Raileen Del Rosario
    Raileen Del Rosario
    The Agreement Trap: How Developers Can Break Free with Docusign IAM

    Secure, verify, comply: Automate identity checks with Docusign APIs

    Author Niani Byrd
    Niani Byrd
    Secure, verify, comply: Automate identity checks with Docusign APIs

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

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting