Docusign: creating envelopes through templates with the REST API and prefilling tags

{ "status": "sent", "emailBlurb": "Please sign the document.", "emailSubject": "Please sign your agreement", "templateId": "TEMPLATE_ID", "templateRoles": [ { "clientUserId": "EMAIL", "name": "NAME", "email": "EMAIL", "roleName": "Signer1", "tabs": { "textTabs": [ { "tabLabel": "address", "value": "ADDRESS " }, { "tabLabel": "multi_address", "value": "ADDRESSES" } ] } }, { "name": "ANOTHER NAME", "email": "ANOTHER EMAIL", "roleName": "Random1" } ] }

Your question says your submitting that JSON to the "Get Recipient View" resource:

https://demo.docusign.net/restapi/v2/accounts/ACCOUNT_ID/envelopes/ENVELOPE_ID/views/recipient)

...but that JSON looks like what you use in the "Create Envelope" request, not the "Get Recipient View" request. So, let me start by clarifying the process of facilitating Embedded/captive signing (i.e., presenting the recipient's envelope within your site). Doing so is a two-step process:

STEP 1: Create the envelope (request includes data to pre-populate fields for each recipient, if needed).

POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes

See "Creating an Envelope From a Template" section that starts on p27 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for detailed info about request and response.

STEP 2: Retrieve the URL that can be used to launch the recipient's envelope (signing session).

POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes/{envelopeId}/views/recipient

{
"authenticationMethod":"Email",
"clientUserId":"CLIENT_USERID_SPECIFIED_IN_REQUEST",
"email":"RECIPIENT_EMAIL",
"returnUrl":"URL_TO_REDIRECT_TO_WHEN_SIGNING_COMPLETE",
"userName":"RECIPIENT_NAME"
}

The response will contain the URL that can be used to launch the Recipient's Envelope:

{
"url":"URL_THAT_WILL_LAUNCH_ENVELOPE"
}

See the "Post Recipient View" section that starts on p160 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for more detailed info about request and response.

Now, assuming you're doing all this correctly (step 1 and step 2) -- let's get back to the issue you're reporting: difficulty pre-populating fields for the recipient. A few comments about the "Create Envelope from Template" JSON that you included in your question:

You don't need accountId in request.
You don't need to include documentId and pageNumber in the request for the tab.
You DO need to include clientUserId for the recipient in the request, if you want the recipient to sign embedded/captive within your site.

So, here's a "Create/Send Envelope From Template" example request (step 1 above) that pre-populates the tab named "FIELD_1" with the value "VALUE_A" anywhere that it appears in the envelope:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
    "status"        : "sent",
    "emailBlurb"    : "please sign",
    "emailSubject"  : "Please sign your document",
    "templateId"    : "TEMPLATE_ID",
    "templateRoles" : [{
      "name"         : "John Doe",
      "email"        : "[email protected]",
      "roleName"     : "Signer1Role",
      "clientUserId" : "123",
      "tabs"         :
         {"textTabs":[{
            "tabLabel":"\\*FIELD_1",
            "value":"VALUE_A"}
         ]}
   }]
}

Then, you'd take the Envelope Id that's returned in the response and call the "Get Recipient View" resource (step 2 above) to get the URL to launch the signing session:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
     "authenticationMethod": "Email",
     "clientUserId": "123",
     "userName": "John Doe",
     "email": "[email protected]",
     "returnUrl": "http://www.google.com"
}

Finally, one last comment (but an important one): if you're just wanting to inject the recipient's "full name" in the document -- use the "Full Name" tab when creating the Template and DocuSign will automatically inject the recipient's name in place of that tag, anywhere that it appears (instead of you using a Text Tab and having to populate it via the API request). Here's the Full Name tag in the DocuSign UI tagger view: Using Full Name tag

Another Create Envelope Example (with screenshot of data field properties):

If I submit this request:

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign this",
  "emailBlurb": "Please sign...thanks!",
  "templateId": "TEMPLATE_ID",
  "envelopeIdStamping": "false",
  "templateRoles": [
   {
      "roleName": "Signer1",
      "name": "John Doe",
      "email": "[email protected]",
      "recipientId": "1",
      "tabs":{
            "textTabs":[
               {
                  "tabLabel":"\\*address",
                  "value":"123 Main Street"
               },
            ],
         }
    }
  ],
  "status": "sent"
}

And the Data Field properties (when Editing the Template via the DocuSign UI) look like this:

Data Field Properties

Then the result is that field(s) with Label = address that are assigned to Recipient Role Signer1 will be prepopulated with the value "123 Main Street" when the signer views their envelope. If this isn't working for you, I suggest that you:

Verify that the value of roleName in the API request exactly matches the Recipient value I've highlighted in the prior screenshot (in my example, "Signer1").
Verify that the value of tabLabel in the API request exactly matches the Label value I've highlighted in the prior screenshot (in my example, "address).

Note: Values are case-sensitive, so be sure values in your request are an exact match (including upper-case/lower-case) with the values in the Data Field Tag Properties.

Recommended topics

Hot tags