Working with Envelope Recipients

Overview

The following operations allow you to work with envelope recipients. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with envelope recipients, see Sample configuration.

Operation details

This section provides details on each of the operations.

Getting the status of envelope recipients

The listReciepentsInEnvelope operation operation allows you to retrieve the status of all recipients in the specified envelope.

<docusign.listRecipientsInEnvelope>
    <accountId>{$ctx:accountId}</accountId>
    <envelopeId>{$ctx:envelopeId}</envelopeId>
	<includeTabs>{$ctx:includeTabs}</includeTabs>
	<includeExtended>{$ctx:includeExtended}</includeExtended>
	<includeAnchorTabLocations>{$ctx:includeAnchorTabLocations}</includeAnchorTabLocations>
</docusign.listRecipientsInEnvelope>

Properties

• accountId :  The ID of the account. This information was returned in the login response.

• envelopeId: The ID of the envelope whose recipient statuses you want to retrieve.

• includeTabs:(optional)When true the tab information associated with the recipient is included in the response.

• includeExtended:(optional)When true the extended properties are included in the response.

• includeAnchorTabLocations:(optional)When true and includeTabs=true, all tabs with anchor tab properties are included in the response.

Sample request

Following is a sample REST request that can be handled by the listRecipientsInEnvelope operation.

{ 
	"apiUrl":"https://demo.docusign.net",
	"apiVersion":"v2",
    "integratorKey":"37f2a694-cf45-4cb3-8ee6-1396b9e75739",  
    "userName":"thulas@gmail.com",
    "password":"XXXXXXXXXXXXX",	"accountId":"1910007",
	"envelopeId":"18f8c59c-da74-4a59-a94d-29accc85f704"
}

Related DocuSign API documentation

https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/list/

Updating recipients

The updateRecipients operation allows you to update recipients in a draft envelope or correct recipient information for an in-process envelope. 

<docusign.updateRecipients>
    <accountId>{$ctx:accountId}</accountId>
    <envelopeId>{$ctx:envelopeId}</envelopeId>
    <carbonCopies>{$ctx:carbonCopies}</carbonCopies>
    <signers>{$ctx:signers}</signers>
    <agents>{$ctx:agents}</agents>
    <certifiedDeliveries>{$ctx:certifiedDeliveries}</certifiedDeliveries>
    <editors>{$ctx:editors}</editors>
    <inPersonSigners>{$ctx:inPersonSigners}</inPersonSigners>
    <intermediaries>{$ctx:intermediaries}</intermediaries>
</docusign.updateRecipients>

Properties

• accountId :  The ID of the account. This information was returned in the login response.

• envelopeId: The ID of the envelope whose recipient statuses you want to retrieve.

• carbonCopies: Recipients who should receive a copy of the envelope.
• signers: Contains information about the signers. For details, see signer in the DocuSign API documentation. 
• agents: Defines the management and access rights of each recipient assigned as an agent on the document. For details, see agent in the DocuSign API documentation.
• certifiedDeliveries: Contains information on a recipient who must receive the completed documents for the envelope to be completed, but the recipient does not need to sign, initial, date, or add information to any of the documents. For details, see certifiedDelivery in the DocuSign API documentation. 
• editors: Defines the management and access rights of each recipient assigned as an editor on the document. For details, see editor in the DocuSign API documentation.
• inPersonSigners: Specifies a signer that is in the same physical location as a DocuSign user who will act as a Signing Host for the transaction. For details, see inPersonSigner in the DocuSign API documentation.
• intermediaries: Identifies a recipient that can, but is not required to, add name and email information for recipients at the same or subsequent level in the routing order. For details, see intermediary in the DocuSign API documentation.

Sample request

Following is a sample REST request that can be handled by the updateRecipients operation.

{
	"apiUrl":"https://demo.docusign.net",
	"apiVersion":"v2",
    "integratorKey":"37f2a694-cf45-4cb3-8ee6-1396b9e75739",  
    "userName":"thulas@gmail.com",
    "password":"XXXXXXXXXXXXX",	
    "accountId":"1910007",
	"envelopeId":"324217fa-df40-4e6c-a25a-0d108674c11d",
	"signers":[{"clientUserId":"911ab6d","email":"thulasika@gmail.com","name":"thulasika@gmail.com","recipientId":"1","roleName":"signer","routingOrder":"1"}]
}

Related DocuSign API documentation

https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/

Sample configuration

Following is a sample proxy service that illustrates how to connect to DocuSign with the init operation and use the listRecipientsInEnvelope operation. The sample request for this proxy can be found in listRecipientsInEnvelope sample request. You can use this sample as a template for using other operations in this category.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="createList"
       transports="https http"
       startOnLoad="true"
       trace="disable">
   <description/>
   <target>
      <inSequence>
        <property name="apiUrl" expression="json-eval($.apiUrl)"/>
		<property name="apiVersion" expression="json-eval($.apiVersion)"/>
        <property name="integratorKey" expression="json-eval($.integratorKey)"/>    
        <property name="userName" expression="json-eval($.userName)"/>
        <property name="password" expression="json-eval($.password)"/>		
        <property name="blocking" expression="json-eval($.blocking)"/>
		<property name="accountId" expression="json-eval($.accountId)"/>
		<property name="envelopeId" expression="json-eval($.envelopeId)"/>
        <docusign.init>
   			 <apiUrl>{$ctx:apiUrl}</apiUrl>
    		 <apiVersion>{$ctx:apiVersion}</apiVersion>
			 <integratorKey>{$ctx:integratorKey}</integratorKey>         
             <userName>{$ctx:userName}</userName>
             <password>{$ctx:password}</password>    			
             <blocking>{$ctx:blocking}</blocking>
		 </docusign.init>
         <docusign.listRecipientsInEnvelope>
    		<accountId>{$ctx:accountId}</accountId>
   			<envelopeId>{$ctx:envelopeId}</envelopeId>
		 </docusign.listRecipientsInEnvelope>
         <respond/>
      </inSequence>
      <outSequence>
         <log/>
         <send/>
      </outSequence>
   </target>
   <parameter name="serviceType">proxy</parameter>
</proxy>