How do I apply a template to a document using Docusign REST API

Question

I'm currently working with the docusign rest API and I'm wondering if anyone has an example of how I can add documents and templates in one envelope. I have access to the template id's I need and I've used composite templates to create an envelope with multiple documents with corresponding templates. I'm doing this ONLY using the template id though. Now I'm trying to figure out how to add a document to the composite template. If the document contains a template(I have access to the template ids if it does have one) it should apply the template to that document.

Can I apply templates to a document through the rest API? If so, does anyone have an example?

Answer 1

Here are a couple of examples that show how Composite Templates can be utilized to combine information from Template(s) with information specified via the API request itself.

Example #1:

The following example request creates an Envelope where the Template is used to define the tags and recipient roles for the Envelope, but the Document and Recipient information is provided by in the API request itself.

POST https://demo.docusign.net/restapi/v2/accounts/ACCOUNTNBR/envelopes HTTP/1.1

X-DocuSign-Authentication: {"Username":"USERNAME","Password":"PASSWORD","IntegratorKey":"INTEGRATORKEY"}
Content-Type: multipart/form-data; boundary=MY_BOUNDARY
Accept: application/json
Host: demo.docusign.net
Content-Length: 162100

--MY_BOUNDARY
Content-Type: application/json
Content-Disposition: form-data

{
    "emailBlurb":"Test Email Body",
    "emailSubject": "Test Email Subject",
    "status" : "sent",
    "compositeTemplates": [
    {
        "serverTemplates": [
        {
            "sequence" : 1,
            "templateId": "TEMPLATE_ID"
        }],
        "inlineTemplates": [
        {
            "sequence" : 2,
            "recipients": {
                "signers" : [{
                    "email": "bettysemail@outlook.com",
                    "name": "Betty Adamson",
                    "recipientId": "1",
                    "roleName": "RoleOne"
                }]
            }
        }],
        "document": {
            "documentId": 1,
            "name": "test1.pdf"
        }
    }]
}

--MY_BOUNDARY
Content-Type: application/pdf
Content-Disposition: file; filename="TestDocAPI.pdf"; documentid="1"

<document bytes removed>

--MY_BOUNDARY--

As shown above, to provide document(s) via the API request itself requires that you submit a multi-part request -- where the first part represents the complete JSON for the Request, and each subsequent Part of the Request represents the contents of a single document that's referenced in the JSON. If your JSON references multiple documents, your request would contain an additional/separate part for each document.

Composite Templates are powerful in that they give you great flexibility in terms of combining information from Templates with information (documents, recipients) provided via the API request itself at runtime. The above example is very simple (one template, one document, one recipient) -- but it can easily be extended for cases where you want to combine multiple templates/documents/recipients.

(The example request on p26-27 of REST API Guide shows the basic format that's required when sending a multi-part request: http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf.)

Example #2:

Next, let's assume that you want to include in an Envelope all of the documents that are defined in a Template, but you also want to include two additional documents (not defined by a Template) in the Envelope. The following example request creates an Envelope with 2 documents that are specified as part of the API request (CustomerAgreement.pdf and Invoice.pdf), and all documents that are defined by the Template that's referenced in the 3rd Composite Template structure. A couple of general notes:

• Documents will appear in the Envelope in the order that they are specified in the JSON request. In this example, that means document order is: 1) CustomerAgreement.pdf (specified via the API request in the first Composite Template structure), 2) Invoice.pdf (specified via the API request in the second Composite Template structure), and 3) all documents specified by the Template that's referenced in the third Composite Template structure.

• Although each individual Composite Template structure must specify recipient info -- DocuSign will match/merge any identical recipient info when forming the recipient collection for the Envelope. In this example, the resulting Envelope has only one recipient: Abby Abbott.

Because we're specifying two documents via the API request, the request has a total of THREE parts: 1) JSON, 2) contents of first document, 3) contents of second document.

POST https://demo.docusign.net/restapi/v2/accounts/ACCOUNTNBR/envelopes HTTP/1.1

X-DocuSign-Authentication: {"Username":"USERNAME","Password":"PASSWORD","IntegratorKey":"INTEGRATORKEY"}
Content-Type: multipart/form-data; boundary=MY_BOUNDARY
Accept: application/json
Host: demo.docusign.net
Content-Length: 162100

--MY_BOUNDARY
Content-Type: application/json
Content-Disposition: form-data

{
    "status" : "sent",
    "emailSubject" : "Test Envelope Subject",
    "emailBlurb" : "Test Envelope Blurb",
    "compositeTemplates": [
    {
        "inlineTemplates": [
        {
            "sequence" : 1,
            "recipients": {
                "signers" : [{
                    "email": "abbysemail@outlook.com",
                    "name": "Abby Abbott",
                    "recipientId": "1"
                }]
            }
        }],
        "document": {
            "documentId": 1,
            "name": "CustomerAgreement",
            "fileExtension": "pdf"
        }
    },
    {
        "inlineTemplates": [
        {
            "sequence" : 2,
            "recipients": {
                "signers" : [{
                    "email": "abbysemail@outlook.com",
                    "name": "Abby Abbott",
                    "recipientId": "1"
                }]
            }
        }],
        "document": {
            "documentId": 2,
            "name": "Invoice",
            "fileExtension": "pdf"
        }
    },
    {
        "serverTemplates": [
        {
            "sequence" : 1,
            "templateId": "TEMPLATE_ID"
        }],
        "inlineTemplates": [
        {
            "sequence" : 2,
            "recipients": {
                "signers" : [{
                    "email": "abbysemail@outlook.com",
                    "name": "Abby Abbott",
                    "recipientId": "1",
                    "roleName": "Initiator",
                    "routingOrder":"1"
                }
                ]
            }
        }]
    }]
}

--MY_BOUNDARY
Content-Type: application/pdf
Content-Disposition: file; filename="CustomerAgreement.pdf"; documentid="1"

    <document bytes removed>

--MY_BOUNDARY
Content-Type: application/pdf
Content-Disposition: file; filename="Invoice.pdf"; documentid="2"

    <document bytes removed>

--MY_BOUNDARY--