How to handle documents for view only in Docusign - docusignapi

This is with the REST api. I have some documents which only need to be viewed, they have no anchor text tags on them. I found that if I gave such documents a server template id, that Docusign would use whichever document was part of the template and not the one I specified. Is the best practice to use certified viewers for such documents and not have them be signers? I noticed that if I had a server template and at least one of my documents had signing tabs, that all the other documents that I wanted to view would be viewable.

Yes, best practice here would be to use a different recipient type other than signer. The certified delivery recipient should work, the carbon copy (cc) recipients should also work well in this case.
Here's what a request with a Carbon Copy recipient in routing order 2 looks like:
{
"emailSubject": "Please sign this doc",
"status": "sent",
"documents": [
{
"documentId": "1",
"name": "test.pdf"
}
],
"recipients": {
"signers": [
{
"email": "signer#email.com",
"name": "John Doe",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"xPosition": "100",
"yPosition": "100",
"documentId": "1",
"pageNumber": "1"
}
]
}
}
],
"carbonCopies": [
{
"email": "carbonCopy#email.com",
"name": "Sally Doe",
"recipientId": "2",
"routingOrder": "2"
}
]
}
}

Related

DocuSign Envelope creation failed containing PDF fields transformation

This is my JSON code so far:
{
"status": "sent",
"emailSubject": "This is an api Demo Doc, sent for signature",
"recipients": {
"carbonCopies": [
{
"email": "nila#gmail.com",
"name": "Nilashree",
"recipientId": "2"
}
],
"signers": [
{
"email": "{{signer1Email}}",
"name": "Nilashree Nandkumar shirodkar",
"recipientId": "1"
}
]
},
"compositeTemplates": [
{
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "nshiro2#students.towson.edu",
"name": "Nila Joseph",
"recipientId": "1",
"defaultRecipient": "true"
}
]
}
}
],
"documents": {
"documentId": "1",
"name": "application_form.pdf",
"transformPdfFields": "true",
"documentBase64": "{{}}"
}
}
]
}
But I am getting the following error:
"errorCode": "ENVELOPE_IS_INCOMPLETE",
"message": "The Envelope is not Complete. A Complete Envelope Requires Documents, Recipients, Tabs, and a Subject Line."
Can anyone please let me know what am I doing wrong?
Why are you using a composite template? Perhaps you are planning towards a later, more complicated envelope definition.
Your mistake is that each composite template can optionally contain only one document. The field name is document, not documents.
Instead of
"documents": {
"documentId": "1",
"name": "application_form.pdf",
"transformPdfFields": "true",
"documentBase64": "{{}}"
}
use
"document": {
"documentId": "1",
"name": "application_form.pdf",
"transformPdfFields": "true",
"documentBase64": "{{}}"
}
Also, I don't believe there's a need for the recipients outside of the composite templates structure. I'm not 100% sure about this issue though.

Docusign API - Create envelope, apply template, prefill values

Many questions address portions of my request, but I cannot seem to make a complete solution work. I have created a template on my site (it has various text fields, initial fields, and signature block). Single recipient, using anchor tags for the fields. When I take a .docx file, create an envelope via the api, I want to apply the template previously mentioned, and then prefill 4 text fields on the document/template.
Anchor tags are not placing the fields appropriately.
Any advise/suggestions?
Working request call is:
{
"documents":
[
{
"documentBase64":"<BASE64STREAM>",
"documentId":"3",
"fileExtension":"docx",
"name":"10001000_20170803_FILE"
}
],
"emailSubject": "TEST - Group Audit - 10001000",
"templateId": "TEMPLATE_ID",
"templateRoles" :
[
{
"email": "JDOE#email.com",
"name": "JOHN DOE",
"roleName": "signer1",
"tabs":
{
"textTabs":
[
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupname",
"value": "TEST GROUP ONE"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupnumber",
"value": "10001000"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "txt",
"value": "my#email.com"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "fein",
"value": "870142380"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "physicaladdress",
"value": "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
],
"status":"sent"
}
Based on the information you've provided, I understand your scenario to be as follows:
You've created a template via the DocuSign UI; that template contains a 'placeholder' document (which you will replace at run-time via your Create/Send Envlope API call) and defines the recipient(s) and tabs for that document.
When you create/send the envelope via API, you want to specify the document as part of the API request (i.e., to be used instead of the 'placeholder' document that the DocuSign template contains) and also auto-populate some of the tabs that the template defines.
If that's an accurate description of what you're trying to achieve, then you need to use Composite Templates in the API request structure. Here's an example of a Create/Send Envelope JSON request that uses composite templates (and contains data based upon the information you provided in your question):
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATE_ID"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "JOHN DOE",
"email": "JDOE#email.com",
"roleName": "signer1",
"tabs":
{
"textTabs":[
{
"tabLabel" : "groupname",
"value" : "TEST GROUP ONE"
},
{
"tabLabel" : "groupnumber",
"value" : "10001000"
},
{
"tabLabel" : "txt",
"value" : "my#email.com"
},
{
"tabLabel" : "fein",
"value" : "870142380"
},
{
"tabLabel" : "physicaladdress",
"value" : "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
]
}
}
],
"document": {
"documentId": "3",
"name": "10001000_20170803_FILE.docx",
"fileExtension": "docx",
"documentBase64": "BASE64STREAM"
}
}
],
"status": "sent",
"emailSubject": "TEST - Group Audit - 10001000"
}

Unexpected behavior with composite templates

I am having an issue with understanding how inline templates work. I have 2 server templates and 2 inline templates, 1 inline template to marry up with a server template. I want to see if I don't fill in the info for the inline template that the envelope still works. Here is my request:
Request
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "8a3a21af-4348-45e1-85b9-72a331c9c67a"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": []
}
}
],
"document": {
"documentId": "2",
"name": "FinalSale.docx",
"fileExtension": "docx",
"documentBase64": [bytearray]
}
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "d22048be-4bfe-43c2-9acf-3d5bcd79144f"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "Kathy Keaton",
"email": "KathyKeaton1#outlook.com",
"recipientId": "1",
"accessCode": "5000",
"routingOrder": "1",
"roleName": "##Buyer1"
},
{
"name": "Kathy Lloyd",
"email": "KathyLloyd1#outlook.com",
"recipientId": "2",
"accessCode": "5000",
"routingOrder": "2",
"roleName": "##Seller1"
}
]
}
}
],
"document": {
"documentId": "1",
"name": "Going to test out signatures and initials.docx",
"fileExtension": "docx",
"documentFields": [
{
"name": "dgsvalue",
"value": "dgs-222"
}
],
"documentBase64": [bytearray]
}
}
],
"status": "sent",
"emailSubject": "Please sign the following 2 documents at 2:39 PM"
}
Response
{
"envelopeId": "f8a090cf-ddc3-4612-8f24-9ff13beddc48",
"uri": "/envelopes/f8a090cf-ddc3-4612-8f24-9ff13beddc48",
"statusDateTime": "2017-02-01T19:39:26.2330000Z",
"status": "sent"
}
I was assuming that the inline templates would have to supply all the signers. The role names in the 2 templates are the same ( ##Buyer1 and ##Seller1 are in both templates ). I would have thought that not having the inline template filled in would mean that it would fail on that particular document. I was wrong, but I'm not sure why. Did it succeed because the role names are the same on both server templates and specifying it for one inline template was enough?
You are not required to supply all the signers in an inline template.
Here are the complete rules for Composite template usage.
Quoting some of them here.
Each CompositeTemplate adds a new document and templates overlay into
the envelope. For each CompositeTemplate these rules are applied:
Templates are overlaid in the order of their Sequence value.
If Document is not passed into the system, the first template’s
document (based on template’s Sequence value) is used.
Last in wins in all cases except for the document (i.e. envelope
information, recipient information, secure field information). This
was done to keep things simple. There is no special casing.
For example, if you want higher security on a tab, then that needs to be specified in the last template in which the tab is included. If you want higher security on a role recipient it needs to be in the last template in which that role recipient is specified.
Recipient matching is based on Recipient Role and Routing Order. If there are matches, the recipient information is merged together. A final pass is done on all CompositeTemplates, after all template overlays have been applied, to collapse recipients with the same email, username and routing order. This prevents having the same recipients at the same routing order.

Signers vs Recipients

We are integrating our BPM application with Docusign. We have a document which should be signed by n individuals. Should we have multiple recipient tags or just 1 recipient tag with multiple signer tags inside that? What would be the difference between both the approaches?
Each Recipient object has properties that identify a specific signer including a property that represents the signer's name, for example). Your "Create Envelope" API request will need to include a separate Recipient object for each Signer -- and then, for each recipient, you'll specify tags that belong to the recipient. (The other approach you describe -- i.e., facilitating multiple people signing an envelope by specifying only one recipient with multiple 'sign here' tags -- is not feasible under any circumstances.)
For example, the recipients structure that represents two Signers, each having one place to sign and one text box to complete, would look something like this:
"recipients": {
"signers": [
{
"name": "John Doe",
"email": "johnsemail#outlook.com",
"recipientId": "1",
"routingOrder": "1",
"clientUserId": "123",
"tabs":{
"signHereTabs":[
{
"tabLabel":"BSign1",
"documentId": "1",
"pageNumber": "1",
"xPosition": "200",
"yPosition": "200"
}
],
"textTabs":[
{
"tabLabel":"BorrowerPhone",
"value":"717-717-7171",
"documentId": "1",
"pageNumber": "1",
"xPosition": "100",
"yPosition": "100"
}
]
}
},
{
"name": "Jane Doe",
"email": "janesemail#outlook.com",
"recipientId": "2",
"routingOrder": "2",
"clientUserId": "567",
"tabs":{
"signHereTabs":[
{
"tabLabel":"CBSign1",
"documentId": "1",
"pageNumber": "2",
"xPosition": "200",
"yPosition": "200"
}
],
"textTabs":[
{
"tabLabel":"Co-BorrowerPhone",
"value":"111-222-3333",
"documentId": "1",
"pageNumber": "2",
"xPosition": "100",
"yPosition": "100"
}
]
}
}
]
}
Taking some time to review the information (and code samples) on the DocuSign Developer Center (https://www.docusign.com/developer-center) and within the REST API Guide (https://10226ec94e53f4ca538f-0035e62ac0d194a46695a3b225d72cc8.ssl.cf2.rackcdn.com/rest-api-guide-v2.pdf) would be time well spent.

Phone Identity with Docusign

I'm looking to build some C# desktop client application that will send out a large number of PDF to sign to a large number of different individual so I'm wondering if the docusign API provide access to automate the Phone identity feature? I was not able to find out the page on their site.
Yes you can access this through the api, the DocuSign Developer Center has pages on the more prevalent features, for full information always check the documentation:
DocuSign API Documentation
You can add a recipient parameter in your request body that sets the idCheckConfigurationName which can be used for an RSA ID check or SMS authentication, and there's also a phoneAuthentication setting which I believe is what you are looking for. The JSON would look something like:
"recipients": {
"signers": [{
"idCheckConfigurationName": "string1",
"phoneAuthentication": "string2"
}]
}
where string1 could be ID Check $ for an RSA ID Check or SMS Auth $ for SMS auth for instance, and string2 is actually made up of a boolean and a list which are used to configure the phone authentication. Please see DocuSign's documentation for more info.
To specify phone authentication for a recipient, you need to specify the following properties for the recipient in the Create Envelope request:
"idCheckConfigurationName": "Phone Auth $",
"requireIdLookup": "true",
"phoneAuthentication": {
"recipMayProvideNumber": "false",
"senderProvidedNumbers": [
"206-222-1111"
]
}
For example, here's a Create Envelope request that specifies phone authentication for the first (and only) recipient.
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"status" : "sent",
"emailBlurb":"Test Email Body",
"emailSubject": "-- Test Email Subject --",
"recipients": {
"signers" : [
{
"email": "bobsemail#outlook.com",
"name": "Bob Adamson",
"idCheckConfigurationName": "Phone Auth $",
"requireIdLookup": "true",
"phoneAuthentication": {
"recipMayProvideNumber": "false",
"senderProvidedNumbers": [
"206-111-2222"
]
},
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"recipientId": "1",
"tabLabel": "Customer_Signature",
"documentId": "1",
"pageNumber": "1",
"xPosition": "99",
"yPosition": "424"
}],
"dateSignedTabs": [
{
"recipientId": "1",
"tabLabel": "Customer_Date",
"documentId": "1",
"pageNumber": "1",
"xPosition": "373",
"yPosition": "456"
}]
}
}]
},
"documents": [
{
"name": "TestDocAPI.pdf",
"documentId": 1,
"documentBase64": "BASE_64_ENCODED_DOCUMENT_BYTE_STREAM"
}]
}
This is just one example -- the properties you set under the phoneAuthentication object may differ depending on your specific requirements. See the DocuSign REST API Guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for information about additional properties available under phoneAuthentication.

Resources