Follow

Submit

Last updated 2018-10-29 13:24:21 UTC

The submit operation allows for a fully automated submission of an AssureSign envelope.  You may submit an envelope that is an instance of an AssureSign Simple Setup template, or you may submit an ad-hoc envelope that does not use a template.

The submit operation requires an active user session. Authentication should be performed using an API User via the method authentication/apiUserAuthentication.

Request with a template

Simple Setup templates allow you to create "sender inputs" that may be mapped to required elements in the envelope's workflow or on the document.

For example, when you create a signer in the template, sender inputs are automatically added to the template (for name, email address and possibly mobile phone number) that need to be filled when the template is used.  You can also create sender inputs that allow you to specify other properties of the envelope, such as the envelope name, a custom order number you want to pass through, and the expiration date of the envelope.

Besides sender inputs that need to be populated with strings of data, to apply the template's signing areas to a document you have created -- instead of using the document used when designing the template -- you may pass in a special sender input that contains file contents that have been converted to a Base64 encoded string.

 

Sample Request

Pass the templateID of the Simple Setup template (you can perform a GET to /templates to see all available templates), and a "values" array of name/value pairs for the sender inputs.  You control the names of the sender inputs, so any submit needs to be adjusted to match what your template requires be sent in.

Adjust the Host to match the location of your AssureSign account

POST /api/documentnow/v3.3/submit
Host: www.assuresign.net
Content-Type: application/json
Accept: application/json
Authorization: bearer allthetokenherexhj23kk5==

{
	"request": {
    	"templates": [{
        	"templateID": "b8f17bae-a89b-4519-ae6f-465031349642",
        	"values": [{
            	"name": "Envelope Name",
            	"value": "My First Submission"
        	}, {
            	"name": "Envelope Order number",
            	"value": "45454889"
        	}, {
            	"name": "Document Order Number",
            	"value": "1234567"
        	}, {
            	"name": "Expiration Date",
            	"value": "5/6/2019"
        	}, {
            	"name": "Language",
            	"value": "en-US"
        	}, {
            	"name": "Signer 1 Name",
            	"value": "John Doe"
    		}, {
            	"name": "Signer 1 Email",
            	"value": "jdoe@example.com"
        	}, {
            	"name": "IRS Form W4 PDF File",
            	"files": [{
                	"fileToUpload": {
                		"data": "base64datahere==",
                		"fileName": "fw4.pdf"
                	},
                	"extension": "pdf"
            	}],
            	"overlayStartPage": 0
        	}]
		}]
	}
}

It is possible to submit multiple templates and files in one operation where all elements submitted  belong to a single envelope.

A successful submit will return an id for the envelope.  This may be used in other operations (or in UI report searches for envelopes) that require an envelope ID.  The authToken is used in legacy SOAP methods and is not required in V3.x methods.

Sample Response:

{
    "messages": [],
    "result": {
        "envelopeID": "92a90c2a-193b-426e-8808-a98301243017",
        "authToken": "b8f920fa-4863-455c-9c12-cfbf1cbc5e28"
    }
}

An array of messages will be returned indicating any warnings that may need to be displayed or processed.  Error conditions that result in the submit operation failing will be returned in the form:

{
    "errorCode": "VALIDATION_FAILED",
    "summary": "Unable to submit due to the following error(s)",
    "details": [
        "Documents[0].Documents.Documents[0].Documents.Fields[5].Fields.SignerInputType: 'SignerInputType' should not be empty.",
        "Documents[0].Documents.Documents[0].Documents.Fields[5].Fields.SignerInputType: 'Signer 1 Multiple Choice (Checkbox)' must not have options defined"
    ]
}

 

Ad-hoc request

It is possible to perform a submit without the need for a template.  Similar to the submit/prepare method, the request content must define all signing areas (defined in a fields collection) which requires knowledge of the layout of the document.  Dynamic signing areas (Dynamic JotBlocks) embedded in the document are not currently supported in V3.x REST submissions.

Sample Request:

The following illustrates some of the possible configurations that could be used to perform a submit of an ad-hoc document.  It is also possible to combine ad-hoc and template request information in a single operation. 

Adjust the Host to match the location of your AssureSign account

POST /api/documentnow/v3.3/submit
Host: www.assuresign.net
Content-Type: application/json
Accept: application/json
Authorization: bearer allthetokenherexhj23kk5==

{
	"request": {
		"content": {
			"addendums": [{
				"file": {
					"fileToUpload": {
						"data": "AddendumFileInBase64==",
						"fileName": "Addendum1.pdf"
					}
				},
				"name": "Addendum 1"
			}],
    		"documents": [{
    			"attachments": [{
					"allowMultipleUploads": true,
					"instructions": "Please upload a copy of your driver's license or other state issued identification.",
					"label": "Personal Identification",
					"required": true,
					"signer": "Signer 1"
				}],
        		"file": {
            		"fileToUpload": {
            			"data": "FileContentsInBase64==",
            			"fileName": "FW4.pdf"
            		}
        		},
        		"fields": [{
            		"name": "Signer 1 Signature",            		        			
            		"borderSides": {
            			"bottom": true,
            			"left": true,
            			"right": true,
            			"top": true
            		},            		
            		"certified": true,
            		"fieldType": "signature",
            		"fontSize": 12,            		
            		"inputType": "signer",            		
            		"instructions": "Click to sign.",            		
            		"pageIndex": 0,            		
            		"penColor": "black",            		
            		"position": {
                		"x": 0.1,
                		"y": 0.1
            		},            		
            		"required": true,
            		"signatureStyle": "drawn",            		
            		"signatureType": "signature",            		
            		"signer": "Signer 1",            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		}
        		}, {
            		"name": "Signer 2 Signature",            		        			
            		"borderSides": {
            			"bottom": true,
            			"left": true,
            			"right": true,
            			"top": true
            		},            		
            		"certified": true,
            		"fieldType": "signature",
            		"fontSize": 12,            		
            		"inputType": "signer",            		
            		"instructions": "Click to sign.",            		
            		"pageIndex": 0,            		
            		"penColor": "black",            		
            		"position": {
                		"x": 0.6,
                		"y": 0.1
            		},            		
            		"required": true,
            		"signatureStyle": "drawn",            		
            		"signatureType": "signature",            		
            		"signer": "Signer 2",            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		}            		
            	}, {
            		"name": "Signer 1 Initials",            		        			
            		"borderSides": {
            			"bottom": true,
            			"left": true,
            			"right": true,
            			"top": true
            		},            		
            		"certified": true,
            		"fieldType": "signature",
            		"fontSize": 12,            		
            		"inputType": "signer",            		
            		"instructions": "Click to initial.",            		
            		"pageIndex": 0,            		
            		"penColor": "black",            		
            		"position": {
                		"x": 0.1,
                		"y": 0.3
            		},            		
            		"required": true,
            		"signatureStyle": "drawn",            		
            		"signatureType": "initials",            		
            		"signer": "Signer 1",            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		}            		
            	}, {
            		"name": "Signer 1 Text",            		        			
            		"borderSides": {
            			"bottom": true,
            			"left": false,
            			"right": false,
            			"top": false
            		},            		
            		"certified": false,
            		"fieldType": "typed",
            		"fontDecoration": {
            			"bold": true,
            			"italic": true,
            			"underline": true
            		},
            		"fontName": "arial",
            		"fontSize": 12,     
            		"formatterCode": null,
            		"formatterName": null,
            		"horizontalAlignment": "right",
            		"inputType": "signer",            		
            		"instructions": "Enter some text.",            		
            		"pageIndex": 0,            		
            		"position": {
                		"x": 0.6,
                		"y": 0.3
            		},            		
            		"required": true,
            		"signer": "Signer 1",    
            		"signerInputType": "free_Text",                   		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		},
            		"sourceGroup": "Text",
            		"validationID": null,
            		"validationMessage": null,
            		"validationRegex": null,
            		"verticalAlignment": "middle",
            		"wordWrap": false
            	}, {
            		"name": "Signer 1 Multiple Choice (Text)",            		        			
            		"certified": false,
            		"fieldType": "typed",
            		"fontDecoration": {
            			"bold": true,
            			"italic": true,
            			"underline": true
            		},
            		"fontName": "arial",
            		"fontSize": 12,     
            		"horizontalAlignment": "right",
            		"inputType": "signer",            		
            		"instructions": "Select an option.",     
            		"options": [{
            			"selected": false,
            			"text": "Option 1",
            			"value": "Option1"
        			}, {
            			"selected": false,
            			"text": "Option 2",
            			"value": "Option2"        				
        			}],
            		"pageIndex": 0,            		
            		"position": {
                		"x": 0.1,
                		"y": 0.5
            		},            		
            		"required": true,
            		"signer": "Signer 1",            		
            		"signerInputType": "multiple_Choice_Text",            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		},
            		"verticalAlignment": "middle",
            		"wordWrap": false
            	}, {
            		"name": "Signer 1 Multiple Choice (Checkbox)",            		        			
            		"fieldType": "typed",
            		"inputType": "signer",            		
            		"instructions": "Select one or more options.",     
            		"options": [{
            			"graphicRenderType": "check",
            			"position": {
            				"x": 0.6,
            				"y": 0.5
            			},
            			"selected": false,
            			"size": {
            				"height": 0.15,
            				"width": 0.1
            			},
            			"text": "Option 1",
            			"value": "Option1"
        			}, {
            			"graphicRenderType": "x",
            			"position": {
            				"x": 0.8,
            				"y": 0.5
            			},
            			"selected": false,
            			"size": {
            				"height": 0.15,
            				"width": 0.1
            			},
            			"text": "Option 2",
            			"value": "Option2"        				
        			}],
            		"pageIndex": 0,            		
            		"position": {
                		"x": 0.6,
                		"y": 0.5
            		},            		
            		"required": true,
            		"signer": "Signer 1",            		
            		"signerInputType": "multiple_Choice_Checkbox",            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		}
            	}, {
            		"name": "Signer 1 Custom Validation",            		        			
            		"borderSides": {
            			"bottom": true,
            			"left": true,
            			"right": true,
            			"top": true
            		},            		
            		"certified": false,
            		"fieldType": "typed",
            		"fontDecoration": {
            			"bold": false,
            			"italic": false,
            			"underline": false
            		},
            		"fontName": "times_New_Roman",
            		"fontSize": 12,     
            		"formatterCode": null,
            		"formatterName": null,
            		"horizontalAlignment": "right",
            		"inputType": "signer",            		
            		"instructions": "Enter a number.",            		
            		"pageIndex": 0,            		
            		"position": {
                		"x": 0.1,
                		"y": 0.7
            		},            		
            		"required": true,
            		"signer": "Signer 1",    
            		"signerInputType": "custom_Validation",                   		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		},
            		"sourceGroup": null,
            		"validationID": null,
            		"validationMessage": "Please enter a number",
            		"validationRegex": "^\\d+$",
            		"verticalAlignment": "top",
            		"wordWrap": false
    			}, {
            		"name": "Fixed Text",            		        			
            		"borderSides": {
            			"bottom": false,
            			"left": false,
            			"right": false,
            			"top": false
            		},            		
            		"certified": false,
            		"fieldType": "typed",
            		"fixedText": "Fixed Text",            		
            		"fontDecoration": {
            			"bold": false,
            			"italic": true,
            			"underline": true
            		},
            		"fontName": "courier_New",
            		"fontSize": 14,     
            		"formatterCode": null,
            		"formatterName": null,
            		"horizontalAlignment": "left",
            		"inputType": "fixed",            		
            		"instructions": null,            		
            		"pageIndex": 0,            		
            		"position": {
                		"x": 0.6,
                		"y": 0.7
            		},            		
            		"size": {
                		"height": 0.1,
                		"width": 0.2
            		},
            		"timing": "on_Document_Start",
            		"verticalAlignment": "top"
    			}],
        		"name": "IRS Form W4",
    			"orderID": "54321"            	
        	}],
    		"signers": [{
        		"email": "jdoe@example.com",
        		"label": "Signer 1",          
        		"name": "John Doe",
        		"password": "pass1",
        		"passwordPrompt": "Please enter the last 4 digits of your account number.",
        		"signatureStyle": "drawn"
        	}, {
        		"email": "kdoe@example.com",
        		"label": "Signer 2",          
        		"name": "Kay Doe",
        		"password": "pass1",
        		"passwordPrompt": "Please enter the last 4 digits of your account number.",
        		"signatureStyle": "drawn"
        	}],
    		"emailNotifications": [{
				"name": "Envelope available to sign",
				"subject": "Please sign your documents - [Envelope Order ID]",
				"body": "You can sign using the following link: [Link - Document Signing]",
				"stage": "step_Start", 
				"step": 0, 
				"recipients": [
					"all_Signers_In_Step" 
				]
			}, {
				"name": "Envelope available to sign",
				"subject": "Please sign your documents - [Envelope Order ID]",
				"body": "You can sign using the following link: [Link - Document Signing]",
				"stage": "step_Start", 
				"step": 1, 
				"recipients": [
					"all_Signers_In_Step" 
				]
			}, {
				"name": "AssureSign signing complete",
				"subject": "Signing is complete - [Envelope Order ID]",
				"body": "Download the signed document here: [Link - Final Document]",
				"stage": "envelope_Complete", 
				"recipients": [
					"All_Signers",
					"Originator",
					"NotificationRecipient1"
				]
			}],
    		"envelope": {
        		"cultureType": "en-US",
        		"declineBehaviorType": "decline_All",  
        		"downloadPassword": "",
        		"expirationDate": "7/25/2019",
        		"name": "My AdHoc envelope",        
        		"orderId": "43453453453",
        		"signingDeviceEnabled": false,
        		"viewBehaviorType": "view_Signer_Only",        
        		"workflowType": "sequential"        
    		},
    		"notificationRecipients": [{
    			"email": "billywagner@anotherplace.com",
    			"label": "NotificationRecipient1",
    			"name": "Billy Wagner"
			}]
    	}
	}
}

 The response on an ad-hoc submit will be the same as the response for a template submit.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.