[FIXED] How to create an envelope with witness for a recipient

Issue

I'm using Docusign in my .NET project. I created the template via docusign UI and I use the templateId when creating Envelope. Since I'm using TemplateId, I need to use TemplateRole instead of Recipients.

TemplateRole signer = new TemplateRole {
   Email = "example@mail.com",
   Name = "David",
   RoleName = "Guarantor",
   Tabs = tabs, //Set tab values
};
List<TemplateRole> templateRoles = new List<TemplateRole> { signer };
EnvelopeDefinition env = new EnvelopeDefinition {
   TemplateId = templateId,
   Status = envStatus,
   TemplateRoles = templateRoles,
};

Now I want to add Witness for the signer. I found this blog post to add witness. But I'm getting the below error when using Recipients attribute.

The request contained at least one invalid parameter. 'recipients' may not be specifed when 'templateId' is set. Use 'templateRoles'.

Is there any way to add witness with templateId?

Solution

Here's a working JSON request (followed by C# code) that updates a server template to:

1. Add a clientUserId to recipient 1 to turn it into an embedded signer (you don't need that part)
2. Add a witness for recipient 1
3. Add a signHere tab for the witness
4. Add a label "witness" under the witness' signature

  "envelopeDefinition": {
    "status": "sent",
    "compositeTemplates": [
      {
        "serverTemplates": [
          {
            "sequence": "1",
            "templateId": "xxx-7d29-490d-9bac-xxxx"
          }
        ],
        "inlineTemplates": [
          {
            "sequence": "2",
            "recipients": {
              "signers": [
                {
                  "clientUserId": "1001",
                  "email": "signer1@example.com",
                  "name": "Signer One",
                  "roleName": "signer1",
                  "recipientId": "1"
                },
                {
                  "email": "",
                  "name": "",
                  "roleName": "signer2",
                  "recipientId": "2"
                }
              ],
              "witnesses": [
                {
                  "recipientId": "3",
                  "witnessFor": "1",
                  "tabs": {
                    "signHereTabs": [
                      {
                        "anchorString": "/sig1/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "150"
                      }
                    ],
                    "textTabs": [
                      {
                        "anchorString": "/sig1/",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "150",
                        "anchorYOffset": "12",
                        "bold": "true",
                        "font": "Helvetica",
                        "fontSize": "Size14",
                        "locked": "true",
                        "value": "Witness"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  },

C# version

// DocuSign Builder example. Generated: Fri, 22 Jul 2022 12:34:39 GMT
// DocuSign (c) 2022. MIT License -- https://opensource.org/licenses/MIT
// @see https://developers.docusign.com -- DocuSign Developer Center

using System.Collections.Generic;
using System.IO;
using System;
using DocuSign.eSign.Api;
using DocuSign.eSign.Client;
using DocuSign.eSign.Model;

namespace CSharp_example
{
    class Program
    {
        // Note: the accessToken is for testing and is temporary. It is only good for 8 hours from the time you 
        //       authenticated with API Request Builder. In production, use an OAuth flow to obtain access tokens.
        private const string accessToken = "Eg";
        private const string accountId = "";
        private const string basePath = "https://demo.docusign.net/restapi";

        // Create the envelope request and send it to DocuSign
        // Returns the resulting envelopeId or ""
        static string SendDocuSignEnvelope()
        {
            ServerTemplate serverTemplate1 = new ServerTemplate
            {
                Sequence = "1",  
                TemplateId = "xxx-7d29-490d-9bac-xxxxxx" 
            };
            List<ServerTemplate> serverTemplates1 = new List<ServerTemplate> {serverTemplate1};
            Signer signer1 = new Signer
            {
                ClientUserId = "1001",  
                Email = "signer1@example.com",  
                Name = "Signer One",  
                RecipientId = "1",  
                RoleName = "signer1" 
            };
            Signer signer2 = new Signer
            {
                Email = null,  
                Name = null,  
                RecipientId = "2",  
                RoleName = "signer2" 
            };
            List<Signer> signers1 = new List<Signer> {signer1, signer2};
            SignHere signHereTab1 = new SignHere
            {
                AnchorString = "/sig1/",  
                AnchorUnits = "pixels",  
                AnchorXOffset = "150" 
            };
            List<SignHere> signHereTabs1 = new List<SignHere> {signHereTab1};
            Text textTab1 = new Text
            {
                AnchorString = "/sig1/",  
                AnchorUnits = "pixels",  
                AnchorXOffset = "150",  
                AnchorYOffset = "12",  
                Bold = "true",  
                Font = "Helvetica",  
                FontSize = "Size14",  
                Locked = "true",  
                Value = "Witness" 
            };
            List<Text> textTabs1 = new List<Text> {textTab1};
            Tabs tabs1 = new Tabs
            {
                SignHereTabs = signHereTabs1,  
                TextTabs = textTabs1 
            };
            Witness witness1 = new Witness
            {
                RecipientId = "3",  
                Tabs = tabs1,  
                WitnessFor = "1" 
            };
            List<Witness> witnesses1 = new List<Witness> {witness1};
            Recipients recipients1 = new Recipients
            {
                Signers = signers1,  
                Witnesses = witnesses1 
            };
            InlineTemplate inlineTemplate1 = new InlineTemplate
            {
                Recipients = recipients1,  
                Sequence = "2" 
            };
            List<InlineTemplate> inlineTemplates1 = new List<InlineTemplate> {inlineTemplate1};
            CompositeTemplate compositeTemplate1 = new CompositeTemplate
            {
                InlineTemplates = inlineTemplates1,  
                ServerTemplates = serverTemplates1 
            };
            List<CompositeTemplate> compositeTemplates1 = new List<CompositeTemplate> {compositeTemplate1};
            EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition
            {
                CompositeTemplates = compositeTemplates1,  
                Status = "sent" 
            };

            ApiClient apiClient = new ApiClient(basePath);
            apiClient.Configuration.AddDefaultHeader("Authorization", "Bearer " + accessToken);
            EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
            try
            {
                EnvelopeSummary results = envelopesApi.CreateEnvelope(accountId, envelopeDefinition);
                Console.WriteLine($"Envelope status: {results.Status}. Envelope ID: {results.EnvelopeId}");
                return results.EnvelopeId;
            }
            catch (ApiException e)
            {
                Console.WriteLine("Exception while creating envelope!");
                Console.WriteLine($"Code: {e.ErrorCode}\nContent: {e.ErrorContent}");
                //Console.WriteLine(e.Message);
                return "";
            }
        }


        // Request the URL for the recipient view (Signing Ceremony)
        static void RecipientView(string envelopeId)
        {
            bool doRecipientView = true;
            RecipientViewRequest recipientViewRequest = new RecipientViewRequest
            {
                AuthenticationMethod = "None",  
                ClientUserId = "1001",  
                Email = "signer1@example.com",  
                UserName = "Signer One" 
            };

            if (!doRecipientView || envelopeId == "")
            {
                return; // EARLY return
            }
            ApiClient apiClient = new ApiClient(basePath);
            apiClient.Configuration.AddDefaultHeader("Authorization", "Bearer " + accessToken);
            EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
            try
            {
                ViewUrl results = envelopesApi.CreateRecipientView(accountId, envelopeId, recipientViewRequest);
                Console.WriteLine("Create recipient view succeeded.");
                Console.WriteLine("Open the signing ceremony's long URL within 5 minutes:");
                Console.WriteLine(results.Url);
            }
            catch (ApiException e)
            {
                Console.WriteLine("Exception while requesting recipient view!");
                Console.WriteLine($"Code: {e.ErrorCode}\nContent: {e.ErrorContent}");
                //Console.WriteLine(e.Message);
            }
        }

        /// <summary>
        /// This method read bytes content from files in the project's Resources directory
        /// </summary>
        /// <param name="fileName">resource path</param>
        /// <returns>return Base64 encoded content as string</returns>
        internal static string ReadContent(string fileName)
        {
            byte[] buff = null;
            string path = Path.Combine(Directory.GetCurrentDirectory(), @"..\..\..\Resources", fileName);
            using (FileStream stream = new FileStream(path, FileMode.Open, FileAccess.Read))
            {
                using (BinaryReader br = new BinaryReader(stream))
                {
                    long numBytes = new FileInfo(path).Length;
                    buff = br.ReadBytes((int)numBytes);
                }
            }
            return Convert.ToBase64String(buff);
        }

        // The mainline
        static void Main(string[] args)
        {
            Console.WriteLine("Starting...");
            string envelopeId = SendDocuSignEnvelope();
            RecipientView(envelopeId);
            Console.WriteLine("Done.");
        }
    }
}

Answered By - Larry K

Answer Checked By - Dawn Plyler (PHPFixing Volunteer)