How to set prefill tabs when creating envelope from template

Hi ​@tzelshy,

Prefill tabs and recipient tabs are different types. You should check in your template which type you’ve used. 

Prefill tabs (gray color in our UI) are meant to be document tabs and not linked to a recipient. They cannot be filled from the envelope creation, and you would need to use any of our EnvelopeDocumentTabs SDK methods to update these values after creating the envelope as a draft. 

Recipient tabs (recipient color defined in the UI) are meant to be tabs set for a recipient. You can prefill the content as you did in your payload, but the prefillTabs object should not be used in this scenario.

The tabs object declaration should be: 

{
    // content removed for brevity

    tabs: {
        textTabs: [
            {
                tabLabel: "name",
                value: "Jabberwocky!",
            },
            {
                tabLabel: "text",
                value: "lorem ipsum"
            }
        ]
    }

    // content removed for brevity
}

Please let us know if this answer helped you, and if so, please mark it as the best answer. 

Regards,

Renan

EnvelopeDocumentTabs methods only work for smartSection and StrikeThrough tabs. I am unable to update pre-fill tabs using the envelopesApi.updateDocumentTabs method. I tried adding the collapsible section under Smart Sections in the template editor UI would fix it, but it did not. If anybody is still checking this thread, it would be a huge help if I could understand pre-fill tabs better.


'INVALID_TAB_OPERATION',
"The Tab specified is not valid for the requested operation. Updated tabs must all be Strikethrough or SmartSection tabs if you're not specifying a valid recipient."

Update: updateDocumentTabs won’t work, but envelopesApi.updateTabs gets us one step further. Except now we get an incomplete error message

Error creating envelope: {
  errorCode: 'INVALID_TAB_OPERATION',
  message: 'The Tab specified is not valid for the requested operation. PrefillTab is'
}

Hi ​@aivnerrad,

The UpdateDocumentTabs are also valid for Prefill Tabs, and you can use this method to modify a document prefill tab regardless of whether it’s on the draft or in-flight stage. You don’t need to set a smartSectionTabs or polyLineOverlayTabs for it to work. You can try to do the following:

1. Create an envelope with a tabs object within the document object (this document contains an anchor tab):
   POST /envelopes
   Request:

   {
   	"status": "sent",
   	"emailSubject": "Sign the following envelope",
   	"emailBlurb": "Please read the document entirely.",
   	"recipients": {
   		"signers": [
   			{
   				"recipientId": "1",
   				"routingOrder": "1",
   				"name": "Mike Cosgrove",
   				"email": "mcosgrove@gmail.com"
   			}
   		]
   	},
   	"documents": [
   		{
   			"documentId": "1",
   			"name": "myDocument1.pdf",
   			"tabs": {
   				"prefillTabs": {
   					"textTabs": [
   						{
   							"anchorString": "/s1/",
   							"value": "Original Sender Text"
   						}
   					]
   				}
   			},
   			"documentBase64": "<base64_string>"
   		}
   	]
   }

2. Get the tabId from the prefill tab you want to modify:
   GET /envelopes/{envelopeId}/documents/{documentId}/tabs
   Response:

   {
   	"prefillTabs": {
   		"textTabs": [
   			{
   				"requireAll": "false",
   				"value": "Original Sender Value",
   				"originalValue": "Original Sender Value",
   				"required": "true",
   				"locked": "true",
   				"concealValueOnDocument": "false",
   				"disableAutoSize": "false",
   				"tabLabel": "",
   				"bold": "false",
   				"italic": "false",
   				"underline": "false",
   				"localePolicy": {},
   				"documentId": "1",
   				"pageNumber": "1",
   				"xPosition": "313",
   				"yPosition": "259",
   				"width": "0",
   				"height": "0",
   				"anchorString": "/s1/",
   				"anchorXOffset": "0",
   				"anchorYOffset": "0",
   				"anchorUnits": "pixels",
   				"anchorCaseSensitive": "false",
   				"anchorMatchWholeWord": "true",
   				"anchorHorizontalAlignment": "left",
   				"anchorTabProcessorVersion": "v1_3",
   				"tabId": "16d8046c-11e6-4c59-9a8b-ed2095f6e8a8",
   				"tabType": "prefilltab"
   			}
   		]
   	}
   }

3. Update the prefill tab, providing the tabId and the new value through the updateDocumentTabs method.
   PUT /envelopes/{envelopeId}/documents/{documentId}/tabs
   Request:

   {
   	"prefillTabs": {
   		"textTabs": [
   			{
   				"tabId": "16d8046c-11e6-4c59-9a8b-ed2095f6e8a8",
   				"value": "Modified Sender Value"
   			}
   		]
   	}
   }

    

The output in the document should be this one:
 

Please try this way and see if it works for you. 

Regards,

Renan

{
	"prefillTabs": {
		"textTabs": [
			{
				"tabId": "16d8046c-11e6-4c59-9a8b-ed2095f6e8a8",
				"value": "Modified Sender Value"
			}
		]
	}
}

Whenever I tried to make this request (PUT /envelopes/{envelopeId}/documents/{documentId}/tabs) using the SDK method updateDocumentTabs, I got an error saying "The Tab specified is not valid for the requested operation. PrefillTab is"

I found a StackOverflow post saying to avoid the Prefill Tab headache, we can use a third recipient and just set the values of the properties shared and locked to true for each tab we want to prefill. This worked for my case. 

Now the tabs that need to be prefilled are assigned to a recipient and we use the updateTabs method to update the recipient tabs.

Thanks for getting back to me!

​@aivnerrad, 

I had the opportunity to find your requests, and it seems that in all your requests where you got the error message "The Tab specified is not valid for the requested operation. PrefillTab is" came from a PUT /envelopes/{envelopeId}/recipients/{recipientId}/tabs instead.

I found no evidence that the updateDocumentTabs returned this error message. 

The Prefill tab is not a recipient-specific tab; it is only for documents. 

For the error message “The Tab specified is not valid for the requested operation. Updated tabs must all be Strikethrough or SmartSection tabs if you're not specifying a valid recipient.”, the updateDocumentTabs was used, but we can’t see the tab or the tab type you were using in your request. We would need to review your request to understand what happened. 

The way that you ran on your side, although not recommended for the purpose, may work to see the text content to an unassigned recipient. 

Regards,

Renan

Ah, yep, that’s exactly it. I had already gotten to the intended functionality, so the exact errors I mixed up. 

For the updateDocumentTabs error, I believe the error was from not specifying the tabId, I was using the tabLabel, but I think without the Id it was throwing this error.

So now I create the envelope, fetch the tabIds, generate the prefill data, map the prefill data to the tabIds, then send the envelope for signature. The part I’m at now is setting up the Connect webhooks so that when the first party signs, we can generate a signing URL for the second party.