We are using embedded Signing feature. We are using templates for generating envelopes for embedded signing. We have a requirement for downloading pdf (before signing). This pdf should contain pre-populated data in envelope. We have tried to download pdf by using rest API as below, but it is giving blank (without prepopulated value - as in template) pdf. Is there any way to achieve the same?
https://demo.docusign.net/restapi/v2/accounts/{our account id}/envelopes/{envolopID}/documents/{documentId}
The way that DocuSign works is that when you layer data fields and other DocuSign tabs onto your documents they are not part of the document until it is signed by the recipients who are to take actions on those tabs. One of the reasons is because someone might change the initial data to something else when it is their turn to sign (if they have permissions to) so when the document is still pending the pre-populated values are not included in the download.
You can, however, still retrieve the values of your fields while the envelope is still pending. Since tabs are always specific to recipients you need to download tab information for whichever recipients they are configured for.
To download the tabs for this recipient including the initial pre-populated values you would make the following api call:
URL:
/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
Formats:
XML, JSON
HTTP Method:
GET
HTTP Body:
(empty)
If the envelope in question had one data field (textTab) which has the value "test data", then the response would look like:
"textTabs": [
{
"height": 11,
"validationPattern": "",
"validationMessage": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"name": "Text",
"value": "test data",
"width": 138,
"required": "true",
"locked": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"tabLabel": "Data Field 3",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "58576405-2f0b-45a4-998b-1cb81b769d22",
"pageNumber": "1",
"xPosition": "105",
"yPosition": "499",
"tabId": "7e1441bc-700e-43d4-b968-b7fa36887ee2"
}
]
Related
I have a Word document that serves as the Document template. It only has an outline on it. I then added text fields to the template.
for example, the template JSON, it looks like this:
"recipients":
{ ...
"signers": [
{ ...
"tabs":
{
"listTabs": [
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "55177519",
"tabType": "list",
"tabLabel": "##parentf2e8b853-3ef1-4872-af19-4f1e3c60a3a7##recipient",
"listItems": [
{
"text": "Dealer",
"value": "Dealer"
},
{
"text": "Customer",
"value": "Customer"
}
],
"required": "true",
"shared": "true",
"value": ""
}
],
"textTabs": [
{
"documentId": "1",
"height": "19",
"pageNumber": "1",
"recipientId": "55177519",
"tabId": "55ab5a10-54d6-4ca0-a66b-7c637c8ad61a",
...
"tabLabel": "DealerPhone",
...
},
My questions are:
How can I get all of the text fields to display the data, no matter who the recipient is- for example, the DealerPhone above? Under "Collaboration", I have set the fields set to "Recipients can Collaborate".
Once the first user selects the user from the drop-down list (the listTab below), I do not want subsequent users to go in and change that selection, but I do need the users to see who the previous / first user selected in that drop-down list.
I can share JSON files of both the template and what I'm sending to create the envelope. The template displays, but the text data is blank.
Sample JSON request body:
{
"email": "...email....",
"name": "Test Dealer",
"roleName": "Dealer",
"tabs": {
"textTabs": [
{
"tabLabel": "DealerPhone",
"value": "1-800-111-2222"
},
{
"tabLabel": "DealerContact",
"value": "Billy Dealer"
}]
}
}],
"emailSubject": "DocuSign API - TEST!!!",
"templateId": "{{templateId}}",
"status": "sent"
}
There's an account-level setting that's relevant here, available from Go to Admin > Sending Settings > When an envelope is sent, write the initial value of the field for all recipients. With that enabled, all pre-populated data will be visible to all recipients. With that disabled, data only gets 'burned in' to the PDF when the assigned recipient completes their role.
If you do not want later recipients to be able to change the value of the dropdown, you will want to disable Collaboration on it. Later signers will be able to see that selection regardless of if Collaboration is enabled or not.
Finally, you'll want to avoid using Conditional Logic on fields that should always appear. Setting a tag to be a conditional child means that it will only appear if circumstances are met.
If recipients sign sequentially (increasing routing order) then every subsequent recipient can see the tabs that prior recipients have filled and they cannot modify them. If you have all tabs assigned to your first recipient, all the other recipients will see them but they'll be read-only for them.
I am trying to update the textTabs for a particular envelope recipient of a draft Docusign envelope.
For this I am using the PUT EnvelopeRecipientTabs endpoint. But I am always getting this error.
I intend to update the value of an existing text tab of the particular recipient.
"textTabs": [
{
"requireAll": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"recipientId": "3",
"tabId": "00000000-0000-0000-0000-000000000000",
"errorDetails": {
"errorCode": "INVALID_TAB_OPERATION",
"message": "The Tab specified is not valid for the requested operation. Tab not found in envelope."
}
}
}
Are you specifying a tabId? You need to. Before your EnvelopeRecipientTabs::update call, call EnvelopeRecipientTabs::list to learn the tabId.
We are using AnchorTags in our documents to place signature elements into PDF documents. So far, signature elements like "SignHere" are working as expected, one click per signature, and being placed correctly into to the documents. We are now attempting to add checkboxes to these documents with AnchorTags and we are running in to some issues with how the checkboxes are 1. labeled and 2. grouped.
According to the DocuSign documentation:
For each group of placed fields, the data label is the same for all fields in the group. This is important for field types which the recipient fills out, such as text fields. If you leave the data labels the same, when the recipient completes any one of the fields in the group, all the other like fields are automatically populated with the same data.
Looking at creating checkboxes with the API, we can use a JSON object like this to assign string values in the document the checkbox tag. This will find the string BOR_2_CHK and place a checkbox at every instance.
PUT /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
{
"checkboxTabs": [
{
"name": "",
"tabLabel": "Checkbox1",
"selected": "false",
"shared": "false",
"required": "false",
"locked": "false",
"documentId": "46688109",
"recipientId": "50556292",
"anchorString": "BOR_2_CHK",
"anchorXOffset": "0",
"anchorYOffset": "0",
"anchorUnits": "pixels",
"anchorCaseSensitive": "false",
"anchorMatchWholeWord": "true",
"anchorHorizontalAlignment": "left",
"tabId": ""
}]}
This effect of this call on a document that has more than one matching AnchorString is that a checkbox will be placed at every matching location, when any of the checkboxes are checked, they are all checked. This is easily reproducible in the DocuSign web site by assigning an "AutoPlace" rule to the document for checkboxes.
This is where things get wierd, when a document that uses AnchorTags to place checkboxes, and there is more than once instance of the AnchorString in the document, the signing ceremony will display multiple checkboxes, but the API only reports that there is a single checkbox tab on the document.
In the following JSON example, there were 3 instances of 2 anchor strings in the document, so that is 6 checkboxes total in the document.
{
"checkboxTabs": [
{
"name": "",
"tabLabel": "Checkbox 0daa7d08-db75-43da-bcee-01a6451a34a5",
"selected": "false",
"shared": "false",
"required": "false",
"locked": "false",
"documentId": "46688109",
"recipientId": "50556292",
"pageNumber": "1",
"xPosition": "74",
"yPosition": "253",
"anchorString": "BOR_2_CHK",
"anchorXOffset": "0",
"anchorYOffset": "0",
"anchorUnits": "pixels",
"anchorCaseSensitive": "false",
"anchorMatchWholeWord": "true",
"anchorHorizontalAlignment": "left",
"tabId": "d87fb774-2b4b-4c86-95b3-e5a730066874"
},
{
"name": "",
"tabLabel": "BOR_1_CHK",
"selected": "false",
"shared": "false",
"required": "false",
"locked": "false",
"documentId": "46688109",
"recipientId": "50556292",
"pageNumber": "1",
"xPosition": "74",
"yPosition": "73",
"anchorString": "BOR_1_CHK",
"anchorXOffset": "0",
"anchorYOffset": "0",
"anchorUnits": "pixels",
"anchorCaseSensitive": "false",
"anchorMatchWholeWord": "true",
"anchorHorizontalAlignment": "left",
"tabId": "966c4273-d4a4-4acd-8ff5-08b27ba69c13"
}
]
}
My question is, how using the DocuSign REST API can I ungroup and make work independently all 6 checkboxes on the document?
The DocuSign website has a button available as part of AutoPlace called "Ungroup", when this is clicked in the UI, the API then shows checkbox tabs for each checkbox that was assigned to the AnchorString, however the "ancorString" attributes have all been stripped from the objects that were ungrouped. I have searched the DocuSign API documentation as well as StackOverflow and have not found any "Ungroup" method or attribute that I can use to accomplish this.
The only way I have found to ungroup the checkboxes is to remove the anchorTag attributes to the object using the EnvelopeTabs:Update method to set them to null. This approach is limited since when I query a list of tabs on the envelope, each group checkbox tabs is only shown as a single object therefore to ungroup 3 checkboxes, I must execute 3 updates, and 2 gets as the tabID for the 2nd and 3rd cheboxes are only available after its predecessor has been altered.
Commonly our documents can have upward of 6 signers, each having 40 or more checkbox elements in a document, that is 240 GET/PUT requests for a single envelope, and would hit the DocuSign rate limit after 4 envelopes.
Thanks in advance for your help,
Based on the information provided by Larry K, I was able to derive a method for "ungrouping" tabs that were assigned using an AnchorString.
Step 1 - Get the envelope information with the "includeAnchorTabLocations" option set.
//Get envelope information
EnvelopesApi envelopesApi = new EnvelopesApi();
EnvelopesApi.ListTabsOptions options = new EnvelopesApi.ListTabsOptions();
options.includeAnchorTabLocations = "True";
Envelope envInfo = envelopesApi.GetEnvelope(accountId, envelopeID);
//Get recipients on envelope
Recipients recips = envelopesApi.ListRecipients(accountId, envelopeID);
RecipientsUpdateSummary updateSummary = new RecipientsUpdateSummary();
//List documents in envelope
EnvelopeDocumentsResult docsList = envelopesApi.ListDocuments(accountId, envelopeID);
Step2 - For each recipient in the envelope update the tabs and remove the AnchorString. In our case, we also wanted each tab to have independent data, so the TabLabel was updated to a unique value as well.
//Remove AnchorString from tabs in documents
foreach (Signer recip in recips.Signers)
{
Tabs tabs = envelopesApi.ListTabs(accountId, envInfo.EnvelopeId, recip.RecipientId, options);
if (tabs.CheckboxTabs != null)
{
foreach ( Checkbox tab in recip.Tabs.CheckboxTabs)
{
// Ungroup checkbox tabs by removing the AnchorString
tab.AnchorString = "";
tab.TabLabel = Guid.NewGuid().ToString();
}
}
envelopesApi.UpdateTabs(accountId, envInfo.EnvelopeId, recip.RecipientId, tabs);
}
Final Note
Since anchor tags are being used, the envelope should be submitted to DocuSign in a "Draft" status initially, this allows DocuSign to process the AnchorStrings in the document. Once processed each Tab will have an X,Y coordinate, allowing the AnchorString to be removed while still maintaining the original location of each TAB in the document. Once done updating tabs, update the envelope info to a status of "sent" and fire the envelopeAPI update method to commit the change.
envInfo.PurgeState = null;
envInfo.Status = "sent";
envelopesApi.Update(accountId, envelopeID, envInfo, null);
You can get a list of all of the fields (tags) for a recipient by using the EnvelopeRecipientTabs: list method, with the query parameter include_anchor_tab_locations set to true:
When set to true, all tabs with anchor tab properties are included in the response.
Unfortunately I don't know an answer to your specific question of how to duplicate the effect of the web tool's "ungroup" command.
Update
See this answer for ungrouping tabs similar to the Docusign web tool's "ungroup" command.
I'm trying to setup a template that will have a number of fields pre-filled out. It should behave exactly the way "Full Name" currently does -- I provide the values when creating the envelope and they show up as read-only additions to the document.
I've tried adding "Data Fields" to the document, however there are two problems:
1) When I setup the envelope via API, I try to preset the values (see below for example), but the values do not show up for the signer. The "" matches what I set the DataField to have.
2) The signer can override those values.
"<customFields>"+
"<textCustomFields>"+
"<textCustomField>"+
"<name>Trip Date</name>"+
"<value>Jul 17-21</value>"+
"</textCustomField>"+
"<textCustomField>"+
"<name>Country</name>"+
"<value>Uganda</value>"+
"</textCustomField>"+
"</textCustomFields>"+
"</customFields>"
What is the proper way of doing this?
If you want to set data fields for your recipients through the API you need to use textTabs. The custom fields that you have referenced are at the envelope level, not the recipient level.
Please go through the DocuSign Developer Center as it covers this info. In particular you should take a look at the Explore -> Features -> Stick-eTabs page. There's a section there called Data Fields which answer all your questions:
https://www.docusign.com/developer-center/explore/features/stick-etabs
You use the tabLabel property to pre-populate them and you need to set them in the tabs section of your request body. For instance, if you had 2 data fields (called "Data Field 1" and "Data Field 2") and you wanted to fill them with "foo" and "bar" and you wanted to make them read-only you could use the following JSON. If you don't want them read-only then set "locked" to "false"...
"tabs": {
"textTabs": [
{
"tabLabel": "Data Field 1",
"value": "foo",
"locked": "true",
"xPosition": "200",
"yPosition": "200",
"documentId": "1",
"pageNumber": "1"
},
{
"tabLabel": "Data Field 2",
"value": "bar",
"locked": "true",
"xPosition": "300",
"yPosition": "200",
"documentId": "1",
"pageNumber": "1"
}]
}
We're developing a project at our company that displays a company roster and allows easy DocuSign paperwork generation with many of the tabs already filled out so that we can cut down on inaccuracy and increase ease of use.
With the REST API, I am able to generate envelopes just fine with templates inside and even fill out some of the tabs for the recipient (the tabs we have information for) with information from our database.
The problem I'm experiencing lies with the list tabs (select drop-down boxes) on the templates. When an envelope is generated from the DocuSign website itself, the select boxes have "-- select --" selected, and I see that on the template editor as well, which is proper because we need the employee or manager to select those things (they're required). However, using the API and not even touching the listTabs when doing a PUT for the recipient tabs, there is no "-- select --" even on the drop-down and the first option on the list tab is pre-selected.
We're still using the DocuSign website (via "Review Documents" in email or simply opening the user's inbox on the website) to fill out the paperwork; the generation is the only thing we do with the API at the moment. This list tab thing is a problem; if someone skips selecting those list tabs, then there's already a pre-selected value that could be wrong. Even when the tab is marked as required, the template sees that there is a value selected and it passes validation. Does anyone know if I'm doing something wrong with the template or API calls here or is this a bug?
I would provide code, but it's scattered across so many Java classes that it would be hard to compile into something easily understood on a stackoverflow question. Not only that, but, as I said, I'm not even touching the listTabs at all when doing a PUT on the recipient tabs.
Thanks for your time.
Ok so I believe this is by design, and if you want the "default select item" in there you just have to add it in. I would imagine that some people do not want a "null" option so the api gives them complete control over the list items, whereas when you send through the console it seems to always have "--select--" as the first option.
When you send through the console the "--select" option has a check mark next to it, which means it's just another list option. I was able to mimic this with the following request body:
{
"emailBlurb": "This goes in the email body",
"emailSubject": "API Signature Request",
"documents": [
{
"documentId": "1",
"name": "document.pdf"
}
],
"recipients": {
"signers": [
{
"email": "<email_address_goes_here>",
"name": "John Doe",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"xPosition": "250",
"yPosition": "75",
"documentId": "1",
"pageNumber": "1"
}
],
"listTabs": [
{
"xPosition": "100",
"yPosition": "90",
"documentId": "1",
"pageNumber": "1",
"recipientId": "1",
"tabLabel": "DropDownList",
"listItems": [
{
"selected": "false",
"text": "--select--",
"value": "--select--"
},
{
"selected": "false",
"text": "One",
"value": "One"
},
{
"selected": "false",
"text": "Two",
"value": "Two"
},
{
"selected": "false",
"text": "Three",
"value": "Three"
}
],
"width": "56"
}
]
}
}
]
},
"status": "sent"
}