I'm building a dynamic PDF in NetSuite. I want to upload it to a new DocuSign envelope using the DocuSign REST API. I've seen a lot of answers, but I'm missing something. I'm finding myself running around in circles in the API and online.
In the DocuSign REST API for [creating Envelopes][1] it details how to add a document to an envelope, specifically using the documents node:
"documents": [{
"documentId": "1",
"name": "contract.pdf",
"documentBase64": "base64 document bytes...",
}],
Is the "name" property the filepath where the document is located in my NetSuite directory? Is it instead expecting the file to already be in the DocuSign document folder? Needing to encode implies the former. Using only a filename implies the latter.
Thank you.
When you set the name property within a document object in a Create Envelope request, you're specifying the name of the document as it'll appear within the Envelope. For example, the name of the document in the following screenshot is dstest.txt (as shown above the document thumbnail in the right pane).
You should set the documentBase64 property to the the base64-encoded string that represents the content of the file. That is, you'll do the following in your code:
Read in the file from where ever it's stored.
Create a string that represents the base64-encoded content of the file.
Set the documentBase64 property within the document object in the Create Envelope request to the base64-encoded string that represents the content of the file.
Related
I have an envelope with a single document and two signers saved as a server-side template. The signers execute the agreement in a specific order. The document has a number of pre-fill fields in it.
I am trying to automate sending this agreement out using Integromat. Unfortunately, Integromat's module doesn't allow for pre-fill fields in templates, leaving me to create the API request manually. This is where I get stuck.
The closest I have come is the JSON request below, POSTed to:
…/v2.1/accounts/{accountId}/envelopes, with capitalised values filled in automatically:
{
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"email": "CLIENT_EMAIL",
"name": "CLIENT_NAME",
"roleName": "Recipient",
"tabs": {
"prefillTabs": {
"textTabs": [{
"tabLabel": "Prefill: Purpose",
"value": "PURPOSE_FIELD_DATA"
}]
}
}
}, {
"email": "STAFF_EMAIL",
"name": "STAFF_NAME",
"roleName": "Company"
}
],
"status": "sent"
}
The response from the API is:
The operation failed with an error. [400] A Required field is
incomplete. TabId: GUI_HERE
What I can't figure out is how to get the pre-fill data submitted since it's not tied to a particular signer. I have scoured the v2.1 API documentation but there is no scenario simple enough for this request.
Apologies if I am missing something obvious here; this is my first rodeo with DocuSign's API.
Do you have any idea what I am doing wrong or, better yet, what the body of the request should be for this (presumably) simple scenario?
Update: For pre-fill tabs, you need to have both the tabId and tabLabel, not enough to just have tabLabel like regular tabs.
My guess is a mismatch of the tabId field for the tabs on your template vs. what's in the API request:
You had this value in your request:
Prefill: Purpose
Does it match how the template was set?
I just tried this with composite templates.
When I added the prefill tabs to a recipient I received the error
Error code: INVALID_TAB_OPERATION.
Message: The Tab specified is not valid for the requested operation.
PrefillTab not allowed for recipient.
which makes sense since prefill tabs are associated with a document, not a recipient.
I tried by adding a document to the composite template, but that didn't work either.
I suggest that you use regular tabs. Mark them locked so they can't be changed. Mark them shared so every signer will see them. Then fill in their values as part of your Envelopes:create call.
Here's a live example of doing this. Note the text2 tab which is locked. (It should have the shared attribute set to true. You can add that from the Tabs/text toolbox on the left.)
Also see this blog post about templates.
Integromat does even without using DocuSign Rest APIs.
You can use Powerforms, it will save your cost for Rest APIs.
I recently did this, but issue is for first recipient, you need to send email manually with powerform link.
Here I dynamically construct PowerForm URL where I pass values to pre populate template fields.
To send email from integromat, you can configure Gmail module or any other email module and create html template where you can append Powerform URL in anchor tag
I have successfully gotten event notifications (webhooks) working with my DocuSign demo account, but when I change the eventData version to restv2.1 by including this in my EventNotification:
eventData: {
version: 'restv2.1'
}
DocuSign seems to start ignoring the value of my includeDocuments argument on the events. What I'm really trying to do is to get notified when each recipient signs (but without the documents), and then also get notified when the envelope is completed (with the documents). However, thanks to the includeDocuments flag having no effect, it seems I only have two options:
Don't get any documents back
Include includeData: ['documents'] in my eventData and get documents back on EVERYTHING. Not just my actual documents, but a certificate document as well.
Has anyone had any luck getting the documents only when you request them with restv2.1?
When you create an Envelope, in the API defined a section for the request, which allows you to define the desired format of the data: connecteventdata
Documentation of this object also links an article, which explains it in more details.
So, you have more options to specify the includeData among with the "documents" example:
The eventNotification object now includes a new attribute, eventData. The attribute is set to an object with three attributes: {version, format, and includeData}
includeData is an array of strings with valid items: "custom_fields", "extensions", "folders", "recipients", "powerform", "tabs", "payment_tabs", "documents", "attachments" - see description by the first link, 1
We have defined a template that will be filled in and signed by our customers. In this template we have some fields that we pre-populate along with some documents that we will attach. The customer will fill in other fields and attach more documents. We are using the REST API to generate the sign request. We are able to generate the correct REST request to fill the tabs in the template, set the recipients and successfully send the signature request. All this works great. But now we're trying to get a document attached to the appropriate SignerAttachmentTab in the template and we cannot get REST to accept it.
We've tried using the Documents field but that doesn't work with templates it seems. We created a composite template and then defined a document for the document, server template for the template itself and an inline template to contain the tab data we want to populate. This keeps generating errors about the tab page number not being right. We've tried different values and we've looked over all the forum posts and documentation related to attaching documents to templates and none of them seem to work.
For the document we specify the file to upload, set the document ID and name. In the server template we specify the template ID. In the inline template we create a recipient, set their information, build up the envelope tabs with the data and then add a SignerAttachmentTab for the document. In this tab we set the document ID to match the document ID from the Document element. We set the tabLabel to the label used in the template itself. We've tried setting pagenumber but that doesn't change anything. All we want is for the document to be sent to the customer. When the open it they can double click the attachment field and view the document we're trying to send.
I'm trying to use the recipe explorer to get this to work using raw REST and it keeps failing with the TAB_PAGENUMBER_IS_NOT_IN_DOCUMENT error. It seems like the document is taking precedence over the template. Unfortunately I cannot change the order of the templates in the editor other than setting the sequence # on the server and inline templates. Here's the request that is generated using DocuSign's test system.
{
"compositeTemplates":[{
"document": {
"documentBase64":"<Base64BytesHere>",
"documentId":"2",
"name":"Test.pdf"
},
"inlineTemplates":[{
"recipients":{
"signers":[{
"email":"abc#def.org",
"name":"Person",
"recipientId":"1",
"roleName":"Sender 1",
"tabs":{
"signerAttachmentTabs":[{
"documentId":"2",
"tabLabel":"MyAttachment"
}],
"textTabs":[{
"tabLabel":"someText",
"value":"Value1" }
]}
}]},
"sequence":"2"
}],
"serverTemplates":[{
"sequence":"1",
"templateId":"guid}]
}],
"emailBlurb":"A message",
"emailSubject":"Test",
"status":"sent"
}
I've looked at the existing posts in the forums and either they don't work for my case or they aren't trying to actually attach the documents to the template but simply include them as a document in addition to the template.
Update
Re:
...associate [a] document to the tab so that the signer will be able to click the attachment field in the document and see the document
Yes, you can now do this by using Smart Sections with a documentHtmlDisplaySettings object in the Envelopes:create request. The collapsed (or collapsible) section can be displayed in different ways:
inline
collapsible
collapsed
continue_button
responsive_table
responsive_table_single_column
print_only
Live examples that you can try online
HTML source document
Word source document
Original answer
Re:
But now we're trying to get a document attached to the appropriate SignerAttachmentTab in the template and we cannot get REST to accept it.
You're trying to use the API to add a document to a SignerAttachmentTab?
This is not supported. Only signers themselves add documents to a SignerAttachmentTab. The API can't do it for them.
Is the issue that you want to make sure that a signer attaches (uploads) a document to the envelope as part of the signing ceremony? You can make the tab non-optional (required). But that won't check the contents of the attached file.
You could use a web hook / Connect to check the file(s) that were attached and, if the right files weren't attached, generate another enveloper for the signer.
I figured out what I was doing wrong. For a template without attachments I was using TemplateRole and EnvelopeTabs. But for attachments, trying to include any document would cause the document to override the template. So I switched to composite template with server and inline templates for the template and data. Trying to add documents in various combinations in the various areas where they are allowed generally caused the request to be sent but with no documents.
The final solution was to go back to the original TemplateRole approach but to create the envelope as a draft. After the draft envelope was created I could then add the document to the envelope. But unfortunately to send the envelope you then have to reattach the recipients. I'm looking to clean that up but otherwise it is working for me now.
When using the DocuSign API to create a new template, is there a way to automatically convert PDF fields to DocuSign SecureFields like there is when using the web console?
Posting to:
https://demo.docusign.net/restapi/v2/accounts/{account_id}/templates
Request body:
{
"emailsubject":"Please sign this",
"templateId":"",
"recipients":{
"signers":[{
"routingOrder":1,
"roleName":"RoleOne",
"recipientId":"1"
}]
},
"envelopeTemplateDefinition":{
"name":"test",
"templateId":""
},
"documents":[{
"documentId":"1",
"name":"Agreement8_7_2012",
"transformPdfFields":"true"
}]
}
I get a successful response and the template is created, just without any DocuSign SecureFields.
First, try setting the defaultRecipient property to true for the recipient:
"recipients":{
"signers":[{
"routingOrder":1,
"roleName":"RoleOne",
"recipientId":"1",
"defaultRecipient":"true"
}]
}
This will tell DocuSign that all PDF fields that are transformed into DocuSign fields should belong to that recipient.
If that change doesn't resolve your issue, then I'd suspect that perhaps it's the properties of the PDF fields that are preventing the transformation from being successful. To troubleshoot, I'd suggest that you do the following:
Verify that the fields in your PDF are amongst the Field Types that DocuSign will convert (i.e.: CheckBox, DateTime, ListBox, Numeric, Radio, Text, Signature, and Password).
Examine field properties in the PDF. Seems like DocuSign may not transform PDF fields that have certain protective properties set (for example, Visible=false -- or for signature fields, Read-Only=true). Perhaps start experimenting with various property settings on a single field, to see if changing field properties in the PDF enables DocuSign to transform that field.
The "Transform PDF Fields" section [starting on page 105] of the DocuSign REST API Guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) contains info about the field transformation process.
Using MS Word documents as our source files, is there a way to include special token characters or MS Word fields inside an uploaded document so that Dousing can read the special tokens or field and replace them with the appropriate tags and signatory data?
This would allow me to adjust our document creation software to insert tokens where we needed tags, along with hidden filed that contained recipient data, and then our users could just click a button to get the contract, upload it to DS and have all the fields and tags populate properly.
Tell me you can do this!
Yes, DocuSign can automatically place DocuSign tabs in documents using "anchor text" that exists in the documents. The "Anchoring tabs" section of the REST API guide (starting on p 292) -- http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf -- provides information about how you can achieve this when creating an Envelope with the REST API.
Using "anchor text" with tabs enables you to have DocuSign automatically add/place the tabs in the documents in each place where the text string you specify (i.e., the "anchor text" string) exists in the document. For example, if your documents contained the string ~s1 in each location where the first signer's signature was required, the REST API request you use to create the envelope would include the following tabs information to have DocuSign automatically add a Signature tab for the signer in each location where ~s1 appears in the documents:
"tabs": {
"signHereTabs": [
{
"anchorString": "~s1",
"anchorXOffset": "1",
"anchorYOffset": "0.5",
"anchorIgnoreIfNotPresent": "false",
"anchorUnits": "inches"
}
]
}
Note: The only property absolutely required to use anchor text for tab placement is anchorString -- I've included some additional properties in the sample above that you may or may not want to utilize. See the REST API guide for information about the meaning/purpose of the other properties included in the sample above.
Yes you can do this with DocuSign, as long as you insert these tokens into the document content itself, once the document is uploaded the DocuSign platform will scan through the content and insert any anchor tags where applicable.
For instance, if you have an invisible string in your Word document that is \s1 and you have a Custom Tag saved in your DocuSign account that has \s1 set for its anchor string then signature tabs (or whatever type of tab you'd like) will be inserted wherever \s1 is found in the document. Or if you don't want to save anchor tags at the account level (which means they are applied on all of your envelopes) you can anchor your tabs through api call(s) so that they are only applied to that envelope.
For more information please see the Tab Positioning section under Explore -> Features in the DocuSign Dev Center:
http://www.docusign.com/developer-center/explore/features/stick-etabs
You'll see that one common approach is to set the font color of these special tokens to the same color as the document background (usually white) which in turn makes them invisible so that you only see the DocuSign tabs at those locations.