We are trying to create a composite template using 2+ templates using the REST API. We create a draft envelope first from the templates, then send the envelope.
We call the REST URI:
https://demo.docusign.net/restapi/v2/accounts/e3a6986d-edb6-465d-8b7a-782867f37dd8/envelopes
with the JSON
Body:
{
"status": "created",
"emailBlurb": null,
"emailSubject": null,
"eventNotification": {},
"compositeTemplates": [
{
"serverTemplates": [
{
"templateId": "4da7730b-fc1a-4ea1-bcd9-bc7e55e13271",
"sequence": 1
}
],
"inlineTemplates": [
{
"sequence": 1,
"recipients": {
"signers": [
{
"roleName": "RoleOne",
"recipientId": "49c9c05b-b0c2-4c68-8260-28b574119e7f",
"name": "Tester N",
"email": "YYYYY#gmail.com"
}
]
}
}
]
},
{
"serverTemplates": [
{
"templateId": "3ae253af-4884-4185-9354-b80f37511ce4",
"sequence": 2
}
],
"inlineTemplates": [
{
"sequence": 2,
"recipients": {
"signers": [
{
"roleName": "RoleOne",
"recipientId": "ee3cb7f5-8c38-4790-af81-2c49726e27c3",
"name": "Tester N",
"email": "YYYYYY#gmail.com"
}
]
}
}
]
}
]
}
This creates the draft envelope, and we can access it and retrieve the tabs. We get the signers information for each template separately with a call to Get Recipients Status
/accounts/e3a6986d-edb6-465d-8b7a-782867f37dd8/envelopes/#{template_id}/recipients
then we "send" the draft envelope using
PUT https://demo.docusign.net/restapi/v2/accounts/e3a6986d-edb6-465d-8b7a-782867f37dd8/envelopes/476ad2d1-2134-402d-9404-ed04df15508f
{"status":"sent"}
and the response is
status: 200 {}
Finally when we try to get the recipients view to show it to the signer using
/accounts/e3a6986d-edb6-465d-8b7a-782867f37dd8/envelopes/476ad2d1-2134-402d-9404-ed04df15508f/views/recipient
We get the error response:
{"errorCode"=>"UNKNOWN_ENVELOPE_RECIPIENT",
"message"=>
"The recipient you have identified is not a valid recipient of the specified envelope."}
Can someone please help determine what we are doing wrong?
Thanks
LON
Related
I am able to send a POST request to send an existing template for signing. What I'm trying to do now is attach a PDF to the signature template. The attached PDF does not need to be signed / is not a template. It is just a PDF copy of a document as an appendix to the contract.
The request is going through ok, but I'm getting the error: "TAB_PAGENUMBER_IS_NOT_IN_DOCUMENT",\r\n "message": "The pagenumber specified in the tab element is not in the document that the tab refers to. Tab on Page 8 of Document 1 for Recipient 1"
JSON:
{
"emailSubject": "Please sign this document set",
"templateId": "xxxxxxx",
"templateRoles": [
{
"email": "email#example.com",
"roleName": "Buyer",
"name": "Buyer Name"
}
],
"documents": [
{
"signerMustAcknowledge": "no_interaction",
"order": "asc",
"name": "MyCompany Quote",
"includeInDownload": true,
"documentId": "2",
"documentBase64": "<base64string>",
"display": "inline"
},
],
"status": "sent"
}
How to attach a document to an online template?
The error you are seeing is because DocuSign will try to replace the document in the template with the file you are providing.
You should be able to add this additional document by using composite templates instead. https://developers.docusign.com/docs/esign-rest-api/how-to/request-signature-composite-template-embedded/
Here is a sample:
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"email": "email#example.com",
"roleName": "Buyer",
"name": "Buyer Name"
}
]
},
"sequence": "1"
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "xxxxxxx"
}
]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "<base64string>",
"documentId": "2",
"fileExtension": "pdf",
"name": "MyCompany Quote"
},
"inlineTemplates": [
{
"sequence": "1"
}
]
}
],
"emailSubject": "Please sign this document set",
"status": "sent"
}
The first composite template is used to populate your existing template with the signers information. The second composite template is where you add the additional document you want your users to sign. You can also include additional tabs inside the inlineTemplates if they are needed in the future
I am trying to use the docusign-node-client to send an envelope using the createEnvelope class. This class sends a REST API request to the /envelopes endpoint. The envelope I am trying to send contains a Composite Template.
Here is the body I am attempting to send to docusign
{
"emailSubject": "Sent from Node SDK",
"emailBlurb": "Email body here",
"customFields": {
"textCustomFields": [
{
"name": "DSFSSourceObjectId",
"required": false,
"show": false,
"value": "dealIdHere"
}
]
},
"compositeTemplates": [
{
"inlineTemplates": [
{
"sequence": "1",
"documents": [
{
"documentBase64": "base64StringHere",
"documentId": "1",
"fileExtension": ".pdf",
"name": "filename.pdf"
}
],
"envelope": {
"emailBlurb": "Email body here",
"emailSubject": "Sent from Node SDK",
"customFields": {
"textCustomFields": [
{
"name": "DSFSSourceObjectId",
"required": false,
"show": false,
"value": "dealIdHere"
}
]
},
"recipients": {
"signers": [
{
"email": "myEmail#domain.com",
"name": "My Name",
"recipientId": "1"
}
]
}
}
}
],
"serverTemplates": [
{
"sequence": "1"
}
]
}
],
"status": "sent"
}
When I send this body I get the following error: "The request contained at least one invalid parameter. Invalid value specified for \'templateId\' in composite template sequence: 1"
If I remove the serverTemplates array, I get this error: "The Envelope is not Complete. A Complete Envelope Requires Documents, Recipients, Tabs, and a Subject Line."
If I include a valid templateId in the serverTemplate object it creates an envelope successfully.
The as is application I am converting to Node JS used the Docusign SOAP API and is able to send composite templates with 1 to many documents. Each of these documents can be associated to their own document template or no docusign template.
Does docusign not accept composite templates without some sort of reference to a template id?
You are specifying the inlineTemplate.envelope property incorrectly. You can define the recipients and custom fields directly within the inlineTemplate. You do not have to specify the emailSubject/emailBlurb within the inlineTemplate.
Also note that the custom fields specified at the root level will be ignored when using composite templates. See this answer
The following json should work for you.
{
"emailSubject": "Sent from Node SDK",
"emailBlurb": "Email body here",
"status": "sent"
"compositeTemplates": [
{
"inlineTemplates": [
{
"sequence": "1",
"documents": [
{
"documentBase64": "base64StringHere",
"documentId": "1",
"fileExtension": ".pdf",
"name": "filename.pdf"
}
],
"customFields": {
"textCustomFields": [
{
"name": "DSFSSourceObjectId",
"required": false,
"show": false,
"value": "dealIdHere"
}
]
},
"recipients": {
"signers": [
{
"email": "myEmail#domain.com",
"name": "My Name",
"recipientId": "1"
}
]
}
}
]
}
]
}
How do I specify prefilled fields with composite templates when creating an envelope.
I tried including the tabs information in the inlineTemplate.recipients.signers[0].tabs, but I get an error that System.String cannot be cast to API_REST.Models.v2.tabs.
If I include information as a template role in templateRoles, it is ignored. The documentation is light on information about how to do this. It seems like the prefill data should be specified in the inline template.
Other open questions I have include what does the recipientId do. What is the clientUserIdused for? We currently set clientUserId to the same value for all signers. I see it's used when signer requests a signature. Should it be unique to every signer for some reason?
It also looks like a single composite template overlays the server and inline templates on top of each other. What's the use case for having multiple server templates or multiple inline templates in a single composite template?
Are there plans to improve the documentation to describe how to use composite templates for various purposes?
Signer/template role:
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"roleName": "role1",
"tabs": {
"textTabs": [
{
"locked": true,
"tabLabel": "\\*FieldName",
"value": "prefillValue"
}
]
}
}
Example request:
{
"compositeTemplates": [
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 1
}
],
"serverTemplates": [
{
"sequence": 1,
"templateId": "templateId1"
}
]
},
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#better.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 2
}
],
"serverTemplates": [
{
"sequence": 2,
"templateId": "templateId2"
}
]
}
],
"emailSubject": "Email subject",
"status": "sent",
"templateId": null,
"templateRoles": null
}
Information on sending an envelope from a server template can be found here.
RecipientID is used by the tab element to indicate which recipient is to sign the Document while the clientuserID specifies if the user is remote or embedded and it is recommended it be unique per signer (but not required).
I'd also suggest reading this page about composite templates, hopefully the concept will make a bit more sense but I am with you that the lack of documentation on composite templates can be troublesome.
Unfortunately, I don't have a sample with tab data included, but adding the tab section under each recipient from my sample below should work with no issues.
{
"emailSubject": "DocuSign Comp Test 1",
"emailBlurb": "Example - Composite Templates",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "templateId1"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "templateId2"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "3",
"templateId": "templateId3"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
}
]
}
I'm having a problem creating an envelope from a composite template and having it not duplicate the recipient. Here is a sample of my call.
{
"emailSubject": "Please complete the following forms",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "5ff1b987-dc38-49b1-b394-840f10ad08bb"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "02d947aa-6320-4a6b-b4b4-79c4c733d0d0"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
}
]
}
When I look at the envelope it has Bob Sample twice in the signing flow. How do I make this call so that only one Bob Sample is required to sign?
I want to create a composite envelope and then do an embedded signing. The issue is that the envelope is created but the call to get the url fails.
First I create the composite envelope:
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes
{
"emailSubject": "DocuSign API - Composite Templates",
"emailBlurb": "Composite Templates Sample 1",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "1AA7BA0B-9079-4F8C-915B-739576297D62"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "77343ECC-391F-46A1-BFC3-92A3CD8C93E3"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder",
"tabs": {
"textTabs": [
{
"tabLabel": "AccountFirstName",
"value": "Client"
},
{
"tabLabel": "AccountLastName",
"value": "Name"
},
{
"tabLabel": "Email1",
"value": "someEmail#email.com"
}
]
}
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "3",
"templateId": "ADADDD87-E831-4EF3-A160-BBE73F449C8E"
}
],
"inlineTemplates": [
{
"sequence": "3",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder"
}
]
}
}
]
}
]
}
The response is:
{
"envelopeId": "99f4c73d-6420-4e3b-88eb-2447139a2616",
"uri": "/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616",
"statusDateTime": "2014-08-14T21:09:09.0430000Z",
"status": "sent" }
Next I try to get the recipient view
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616/views/recipient
{
"authenticationMethod": "email",
"email": "email#email.com",
"returnUrl": "www.someUrl.com",
"userName": "Signer Name"
}
And I get this error:
{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the specified envelope. Envelope recipient could not be determined. 'clientUserId', 'email', or 'userName' in request and envelope may not match."
}
The email and the names match up so I do not understand why I am unable to get the url. I should point out that this all works if I use the same name and email that is on the DocuSign account, but this needs to work for an external recipient.
To designate a recipient as an embedded/captive recipient when creating an Envelope, such that you'll subsequently be able to submit a "Get Recipient View" request to retrieve a URL that can be used to initiate the recipient's signing session, your "Create Envelope" request must specify the clientUserId property for the recipient. This property should appear as a peer to the other recipient properties (i.e.: email, name, etc.) -- like this:
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder",
"clientUserId": "12345"
}
]
Then, when you submit the "Get Recipient View" request, you'll need to specify the same value for clientUserId there:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "Email",
"email": "email#email.com",
"returnUrl": "www.someUrl.com",
"userName": "Signer Name",
"clientUserId": "12345"
}
The value of clientUserId can be anything you wish, but max length is 100 characters. See the DocuSign REST API Guide for more details about embedded signing.