Blog
Home/

Common API Tasks🐈: Adding initials in each page of each document of your envelope

Inbar Gazit
Inbar GazitSr. Manager, Developer Content
Summary3 min read

Find out how to insert initial tabs on every page of your documents with the eSignature REST API.

    • Code snippets
    • C#
    • Java
    • Node.js
    • PHP
    • Python
    • Ruby
    • Additional resources

    Table of contents

    Common API Tasks: initial every page

    Welcome to another edition of the CAT🐈 (Common API Tasks) blog. This blog series is about giving you all you need to complete small, specific, SDK-supported tasks using one of our APIs

    You can find all articles in this series on the Docusign developer blog. 

    Our task this time is pretty straightforward to explain, but maybe not as trivial to implement in your code. Assume you have a set of documents that you need to have someone initial—meaning, you just need them to put their initial on every single page of every single document. Back in ancient times (using paper), the person asking you to sign would simply indicate, “please initial on every page…”. How would you do this with Docusign? 

    One option is to use Docusign [free-form signing](Adding initials in each page), where the signer can then drag-and-drop their initials into each page. That option is not ideal because the user can make mistakes and might forget one of the pages, and then you’ll have to start all over again.

    As a user, it’s much easier to just click through all the pages as directed by the Docusign signing UI. To enable that, you must tag the envelope and the documents in the way you want them to be presented to the signer.

    Code snippets

    Before I give you the code in our usual six languages, it’s important to mention that this code assumes you already have a draft envelope with documents and recipients (and you grabbed its envelopeId, which is the GUID uniquely identifying an envelope). You may already have additional tabs (signing elements) as well, and this code won’t impact them. This code simply adds a single initial tab for each signer on each page of each document. 

    Note that this code makes more than one API call. It first makes an API call to get all the information about the documents and recipients in the envelope. Then, for each recipient the code adds new tabs using the EnvelopeRecipientTabs:create endpoint.

    C#

    // You need to obtain an access token using your chosen authentication flow var apiClient = new ApiClient(basePath);
    apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
    EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
    
    EnvelopesApi.GetEnvelopeOptions options = new EnvelopesApi.GetEnvelopeOptions { include = "documents,recipients" };
    Envelope env = envelopesApi.GetEnvelope(accountId, envelopeId, options);
    foreach (Signer signer in env.Recipients.Signers)
    {
      signer.Tabs = new Tabs();
      signer.Tabs.InitialHereTabs = new List<initialhere>();
      foreach (EnvelopeDocument doc in env.EnvelopeDocuments)
      {
        foreach (Page page in doc.Pages)
        {
          int width = int.Parse(page.Width);
          int height = int.Parse(page.Height);
          var initial = new InitialHere();
          // 100 pixels higher and to the left from the top bottom corner
          initial.XPosition = (width - 100).ToString();
          initial.YPosition = (height - 100).ToString();
          initial.PageNumber = page.Sequence;
          initial.DocumentId = doc.DocumentId;
          initial.RecipientId = signer.RecipientId;
          signer.Tabs.InitialHereTabs.Add(initial);
        }
      }
      envelopesApi.CreateTabs(accountId, env.EnvelopeId, signer.RecipientId, signer.Tabs);
    }</initialhere>
    

    Java

    // You need to obtain an access token using your chosen authentication flow 
    Configuration config = new Configuration(new ApiClient(basePath));
    config.addDefaultHeader("Authorization", "Bearer " + accessToken);
    EnvelopesApi envelopesApi = new EnvelopesApi(config);
    
    EnvelopesApi.GetEnvelopeOptions options = envelopesApi.new GetEnvelopeOptions();
    options.setInclude("documents,recipients");
    Envelope env = envelopesApi.getEnvelope(accountId, envelopeId, options);
    for (Signer signer : env.getRecipients().getSigners())
      {
      signer.setTabs(new Tabs());
      signer.getTabs().setInitialHereTabs(new java.util.List<initialhere>());
      for (EnvelopeDocument doc : env.getEnvelopeDocuments())
        {
          for (Page page : doc.getPages())
          {
          int width = Integer.parseInt(page.getWidth());
          int height = Integer.parseInt(page.getHeight());
          InitialHere initial = new InitialHere();
          // 100 pixels higher and to the left from the top bottom corner
          int x = width - 100;
          int y = height - 100;
          initial.setXPosition(x.toString());
          initial.setYPosition(y.toString());
          initial.setPageNumber(page.getSequence());
          initial.setDocumentId(doc.getDocumentId());
          initial.setRecipientId(signer.getRecipientId());
          signer.getTabs().getInitialHereTabs().Add(initial);
          }
        }
      envelopesApi.createTabs(accountId, env.getEnvelopeId(), signer.getRecipientId(), signer.getTabs());
      }
    </initialhere>
    

    Node.js

    // You need to obtain an access token using your chosen authentication flow 
    let dsApiClient = new docusign.ApiClient();
    dsApiClient.setBasePath(basePath);
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
    let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
    
    let options = { include: 'documents,recipients' };
    let env = envelopesApi.getEnvelope(accountId, envelopeId, options);
    env.recipients.signers.forEach(signer => {
      signer.tabs = new docusign.Tabs();
      signer.tabs.initialHereTabs = [];
      env.envelopeDocuments.forEach(doc => {
        doc.pages.forEach(page => {
          let initial = new docusign.InitialHere();
          // 100 pixels higher and to the left from the top bottom corner
          let x = page.width - 100;
          let y = page.height - 100;
          initial.xPosition = x;
          initial.yPosition = y;
          initial.pageNumber = page.sequence;
          initial.documentId = doc.documentId;
          initial.recipientId = signer.recipientId;
          signer.tabs.initialHereTabs.push(initial);
        });
      });
      envelopesApi.createTabs(accountId, env.envelopeId, signer.recipientId, { tabs: signer.tabs });
    });
    

    PHP

    # You need to obtain an access token using your chosen authentication flow 
    $api_client = new \Docusign\eSign\client\ApiClient($base_path);
    $config = new \Docusign\eSign\Model\Configuration($api_client);
    $config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
    $envelopes_api = new \Docusign\Api\EnvelopesApi($config);
    
    $options = new Docusign\eSign\Api\EnvelopesApi\GetEnvelopeOptions();
    $options->setInclude('documents,recipients');
    $env = $envelopes_api->getEnvelope($account_id, $envelope_id, $options);
    foreach ($env->getRecipients()->getSigners() as $signer)
      {
      $signer->setTabs(new \Docusign\eSign\Model\Tabs());
      $signer->getTabs()->setInitialHereTabs([]);
      foreach ($env->getEnvelopeDocuments() as $doc)
        {
        foreach ($doc->getPages() as $page)
          {
          $initial = new \Docusign\eSign\Model\InitialHere();
          # 100 pixels higher and to the left from the top bottom corner
          $x = $page->getWidth() - 100;
          $y = $page->getHeight() - 100;
          $initial->setXPosition($x);
          $initial->setYPosition($y);
          $initial->setPageNumber($page->getSequence());
          $initial->setDocumentId($doc->getDocumentId());
          $initial->setRecipientId($signer->getRecipientId());
          array_push($signer->getTabs()->getInitialHereTabs(), $initial);
          }
        }
      $envelopes_api->createTabs($account_id, $env->getEnvelopeId(), $signer->getRecipientId(), $signer->getTabs());
      }
    

    Python

    # You need to obtain an access token using your chosen authentication flow 
    api_client = ApiClient()
    api_client.host = base_path
    api_client.set_default_header('Authorization', 'Bearer ' + access_token)
    envelopes_api = EnvelopesApi(api_client)
    
    env = envelopes_api.getEnvelope(account_id, envelope_id, include = 'documents,recipients')
    for signer in env.recipients.signers :
      signer.tabs = Tabs()
      signer.tabs.initial_here_tabs = []
      for doc in env.envelope_documents :
        for page in doc.pages : 
          initial = InitialHere()
          # 100 pixels higher and to the left from the top bottom corner
          x = page.width - 100
          y = page.height - 100
          initial.x_position = x
          initial.y_position = y
          initial.page_number = page.sequence
          initial.document_id = doc.document_id
          initial.recipient_id = signer.recipient_id
      signer.tabs.initial_here_tabs.insert(initial)
      envelopes_api.create_tabs(account_id, env.envelope_id, signer.recipient_id, signer.tabs)
    

    Ruby

    # You need to obtain an access token using your chosen authentication flow 
    config = DocuSign_eSign::Configuration.new
    config.host = base_path
    api_client = DocuSign_eSign::ApiClient.new config
    api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
    envelopes_api = DocuSign_eSign::EnvelopesApi.new api_client
    
    options = DocuSign_eSign::GetEnvelopeOptions.new 
    options.include = 'documents,recipients'
    env = envelopes_api.getEnvelope(account_id, envelope_id, options)
    env.recipients.signers.each { |signer|
      signer.tabs = DocuSign_eSign::Tabs.new
      signer.tabs.initial_here_tabs = []
      env.envelope_documents.each { |doc|
        doc.pages.each { |page|
          initial = InitialHere()
          # 100 pixels higher and to the left from the top bottom corner
          x = page.width - 100
          y = page.height - 100
          initial.x_position = x
          initial.y_position = y
          initial.page_number = page.sequence
          initial.document_id = doc.document_id
          initial.recipient_id = signer.recipient_id
          signer.tabs.initial_here_tabs.append(initial)
          }
        }
      envelopes_api.create_tabs(account_id, env.envelope_id, signer.recipient_id, signer.tabs)
      }
    

    That's it folks. As usual, if you have any questions, comments, or suggestions for topics for future Common API Tasks posts, feel free to email me. Until next time…

    Additional resources

    Inbar Gazit
    Inbar GazitSr. Manager, Developer Content

    Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.

    More posts from this author

    Related posts

    • Developers

      What Are API Services? Benefits & Uses

      Docusign Contributor
    • Fast-Track Your Extension Apps with Reference Implementations

      Karissa Jacobsen
      Karissa Jacobsen
    • Paige Rossi
      Paige Rossi

    Fast-Track Your Extension Apps with Reference Implementations

    Karissa Jacobsen
    Karissa Jacobsen
    Paige Rossi
    Paige Rossi

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

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting