Submitting a document containing Dynamic JotBlocks

Last updated 2020-05-14 14:40:35 UTC

See the documentation for the (V3.x) Submit method for isolated examples submitting with and without a template.

It is possible to combine elements of both to accomplish more complex submission scenarios.

The following example -- available for use starting with version 3.4 of the DocumentNOW REST methods -- combines the use of a partial template that does not contain a document with an ad-hoc submit of a document. When a template contains a sender input for a document to be supplied, it is passed in the values section of the template structure.

In this example, the ad hoc document is submitted using the content/documents/file section of the json request packet in the same way as an ad-hoc submit without the use of a template. 

Adjust the Host to match the location of your AssureSign account

POST /api/documentnow/v3.4/submit
Content-Type: application/json
Accept: application/json
Authorization: bearer allthetokenherexhj23kk5==

	"request": {
				"file": {
            		"fileToUpload": {
            			"data": "base64datahere==",
                		"fileName": "contract.docx",
                		"parseDocument": true,
        		"name": "Contract"
    	"templates": [{
        	"templateID": "b8f17bae-a89b-4519-ae6f-465031349642",
        	"values": [{
            	"name": "Envelope Name",
            	"value": "My Envelope"
        	}, {
            	"name": "Envelope Order number",
            	"value": "134567-34"
        	}, {
            	"name": "Expiration Date",
            	"value": "7/25/2019"
        	}, {
            	"name": "Signer 1 Name",
            	"value": "Margo Winfield"
    		}, {
            	"name": "Signer 1 Email",
            	"value": ""

Since no document was present in the template, no JotBlocks could have been designed, and the template is a "partial template".  But passing in a document that contains dynamic JotBlocks allows the template to still be used.

We indicate that the file needs to be opened to detect dynamic JotBlock text in the body by passing:




Currently, the Dynamic JotBlock text syntax supports only the V2 type (the syntax supported in V1 and V2 DocumentNOW methods). The V2 dynamicDocumentVersion specification is required to future-proof the method for when other versions of the dynamic text syntax are introduced.

If sending a file as a sender input with a template, the parseDocument and dynamicDocumentVersion attributes can be added to the "filesToUpload" element to accomplish the same behavior.

To assign a Dynamic JotBlock to a specific signer, use the SignatoryEmailParameterName and enter the name of a Simple Setup template sender input for a signer's email address or mobile phone number.  In this case, our template contains a sender input "Signer 1 Email" so we assign a dynamic JotBlock in the body of the document using this syntax:

FormatterName:"Credit Card Mask",SignatoryInputType:"CustomValidation",
ValidationMessage:"Please enter 16 digit Credit Card Number",
Instructions:"Credit Card Number:",
SignatoryEmailParameterName:"Signer 1 Email"}##!}}

If the signer is identified instead by a mobile phone number, then SignatoryMobilePhoneParameterName should be used instead.  See documentation for these attributes here:

The response structure remains the same for this mixed submit operation.

When creating an ad hoc document using a V3.x API submission, there is an additional mechanism for identifying the signer to whom a new JotBlock is assigned.  Instead of specifying the SignatoryEmail using the email address of the signer, you can specify the signer label.

So for a submit that contains a signer to whom the label "Signer 1" has been assigned as in the following JSON segment ...

POST /Submit
    "request": {
        "content": {
            "signers": [
                    "label": "Signer 1",
                    "email": "",
                    "name": "John Doe"

... the following embedded text would assign the JotBlock to that signer by setting SignatoryEmail to "Signer 1":

{{!##{Name:"CustomerInitials",InputType:"Signatory",FieldType: "Written",Border:"All",InkColor:"Blue",
Instructions:"Please use the mouse to write your initials indicating you agree with this section.",
Height:"0.05",Width:"0.15", SignatoryEmail:"Signer 1"}##!}}
Have more questions? Submit a request