Creating Template with Transformed PDF Form Fields

Question

I have a need to add Docusign templates programmatically, configured with a single PDF document containing multiple form fields. I'm presently able to create a new template, although the PDF form fields are not being transformed to docusign fields.

When creating the template, the JSON payload looks as follows, submitted with an HTTP POST to [baseUrl]/templates as a multipart request, PDF included.

{
  "documents": [
    {
      "documentId": "1",
      "name": "fillable-form.pdf",
      "transformPdfFields": "true"
    }
  ],
  "emailSubject": "Default Blurb",
  "enableWetSign": "false",
  "envelopeTemplateDefinition": {
    "name": "My Template Name",
    "shared": "false",
    "folderName": "Template Folder"
  },
  "recipients": {
    "signers": [
      {
        "routingOrder": "1",
        "recipientId": "1",
        "roleName": "primary-signer",
        "defaultRecipient": "true"
      }
    ]
  }
}

The Post Template Documentation claims that you should be able to enable the transformPdfFields property, in accordance with the Document parameter specification, but setting that property seems to have no effect.

I found a similarly related question asked in DocuSign API auto convert PDF fields to SecureFields, but there was no real sufficient response. I'd like to know if Docusign can weigh in and provide some guidance.

---

Update #1

Heeding the advice provided by @ergin, I've altered my request payload slightly (note, this is similar to the attempt made earlier in response to @c-davis).

Unfortunately, following the suggestion described in Case 2 (It can be used to CREATE NEW TABS from existing PDF Form Fields), it doesn't seem to work as expected.

It's important to note that this is Template creation, rather than Envelope creation.

Attempt #1:

{
  "envelopeTemplateDefinition": {
    "name": "Test Template Name",
    "shared": false,
    "folderName": "test-folder"
  },
  "emailSubject": "Test Subject",
  "enableWetSign": false,
  "compositeTemplates": [
    {
      "inlineTemplates": [
        {
          "sequence": 1,
          "recipients": {
            "signers": [
              {
                "recipientId": 1,
                "roleName": "primary-signer",
                "defaultRecipient": true
              }
            ]
          }
        }
      ],
      "document": {
        "documentId": 1,
        "name": "test-document.pdf",
        "transformPdfFields": true
      }
    }
  ]
}

The result, when sending that in the multipart request, with the second bit of the multipart being the PDF document as normal is that the Template both has no recipient specified and no document.

Attempt #2 (denoting the recipient property of the template request):

{
  "envelopeTemplateDefinition": {
    "name": "Test Template Name",
    "shared": false,
    "folderName": "test-folder"
  },
  "emailSubject": "Test Subject",
  "enableWetSign": false,
  "compositeTemplates": [
    {
      "inlineTemplates": [
        {
          "sequence": 1,
          "recipients": {
            "signers": [
              {
                "recipientId": 1,
                "roleName": "primary-signer",
                "defaultRecipient": true
              }
            ]
          }
        }
      ],
      "document": {
        "documentId": 1,
        "name": "test-document.pdf",
        "transformPdfFields": true
      }
    }
  ],
  "recipients": {
    "signers": [
      {
        "recipientId": 1,
        "roleName": "primary-signer",
        "defaultRecipient": true
      }
    ]
  }
}

The result is slightly closer – the recipient is now listed as one would expect, however the document is still not being considered as part of this template. The only way that the document is associated with the template is when I set that as the outer property of the template creation.

Attempt #3 (denoting both the recipient & document properties of the template request):

{
  "envelopeTemplateDefinition": {
    "name": "Test Template Name",
    "shared": false,
    "folderName": "test-folder"
  },
  "emailSubject": "Test Subject",
  "enableWetSign": false,
  "compositeTemplates": [
    {
      "inlineTemplates": [
        {
          "sequence": 1,
          "recipients": {
            "signers": [
              {
                "recipientId": 1,
                "roleName": "primary-signer",
                "defaultRecipient": true
              }
            ]
          }
        }
      ],
      "document": {
        "documentId": 1,
        "name": "test-document.pdf",
        "transformPdfFields": true
      }
    }
  ],
  "recipients": {
    "signers": [
      {
        "recipientId": 1,
        "roleName": "primary-signer",
        "defaultRecipient": true
      }
    ]
  },
  "documents": [
    {
      "documentId": 1,
      "name": "test-document.pdf",
      "transformPdfFields": true
    }
  ]
}

The result on this final attempt is similar to that of including the recipients and documents properties and eliminating the compositeTemplates property entirely (it seems that property has no effect whether it's present or not). The recipient placeholder is present and the document is associated with the template, however the PDF fields within the PDF document are not "assigned"/converted to Docusign fields.

Answer 1

as far as the transormPdfFields parameter is concerned, I've only ever been able to make this parameter work when associated with a document that is inside a CompositeTemplate. Granted, I'm talking about sending an envelope here, but I bet the same is true when creating a template, even though the documentation may appear otherwise.

I don't have a code sample for this specific call, but if I get some free time I'll try to put one together.

Answer 2

So this is not well documented (soon to be improved) but the transformPdfFields property has two different purposes based on how/where you use it in your request body.

• Case 1: It can be used to TRANSFER THE VALUES contained within existing PDF Form Fields into DocuSign tabs.
• Case 2: It can be used to CREATE NEW TABS from existing PDF Form Fields.

For #1 the names of the PDF form fields need to correspond to the tabLabels of your DocuSign tabs. Sample JSON for to accomplish this would be:

{
    "emailSubject": "test subject",
    "documents": [
    {
        "documentId": "1",
        "name": "document.pdf",
        "transformPdfFields": true
    }
}

---

For #2, you need to use the compositeTemplates structure with the transformPdfFields property enabled in the inline template section to have the platform CREATE new DocuSign tabs. You should also remember to set the defaultRecipient property to true for your recipient so the system knows who to assign thew newly created tabs to (i.e. you can't have un-assigned tabs).

For instance, the following JSON should work:

{
    "compositeTemplates": [{
        "inlineTemplates": [{
            "sequence": 1,
            "recipients": {
                "signers": [{
                    "email": "johndoe@email.com",
                    "name": "John Doe",
                    "recipientId": "1",
                    "defaultRecipient": true
                }]
            }
        }],
        "document": {
            "documentId": 1,
            "name": "Contract.pdf",
            "transformPdfFields": true
        }
    }]
}