The Submit operation is used to launch an instance of a Template where a document is not sent in the communication and does not need to be externally retrieved. Any values passed as pre-fill information for the document will be applied and be made visible to any signers of the document. The workflow and email designs attached to a template will be used, along with any dynamically populated information intended to guide the flow of the document.
The Submit operation requires knowledge of the following:
- the Template ID of the Template to use (this may be viewed for a given template from the Classic Templates tab)
- the AssureSign account ContextIdentifier (this is exposed in the AssureSign administrative application account settings and serves to provide some security to the transaction). The ContextIdentifier is in the form of a global unique identifier (GUID).
- the UserName of the AssureSign user that will be the owner of the document within AssureSign
- the defined parameters that are required to be filled in on the Template. Note that the count and content of these will vary depending on how you have set up your document template. For example, if your data supports passing the first and last name for a signatory, and your document template differentiates these as distinct data fields, then you will pass the values as distinct fields (named according to your own naming convention that you specified on the template); if your data only provides signatory names as full un-parsed values, then you may tailor the document template to receive data in a single parameter. The parameter names provided here must either match the user-defined parameter names provided when the parameters were created for the template or a pre-defined system parameter name (ex. “Signatory 1 Email Address”).
- It is also possible to pass parameters into AssureSign that are not defined in the template and do not map to any JotBlocks or workflow elements (signatory name or email, etc). These parameters can be passed into AssureSign in the same way that template parameters are passed in, and AssureSign will encrypt and store them as usual. While AssureSign will not make use of these “unbound” parameters, they will be available to be referenced as custom merge fields in DocumentTRAK designs to facilitate passing data through AssureSign.
An optional password may be passed as an attribute within the Metadata element. If a password is specified, then access to the signed document will require knowledge of the password. If this document is being added to an envelope, a password should not be specified here as the completed document will be protected by the password set for the envelope. Signatory passwords protect a signing session; the document password passed in the metadata protects the completed document. Other important attributes in the Metadata are:
- the UserName of the AssureSign user that will be the owner of the document
- the name of the document (assigned by you for your purposes)
- an optional ExpirationDate, which is the date the document will expire. If not specified, the expiration date will be set based on the default expiration period for the account. If this document is being added to an envelope, an expiration date should not be specified here as the document will expire based on the expiration date set for the envelope.
- an optional OrderNumber, which is designed to provide you a way to store your unique order number or key to identify the document
- an optional Culture indicator used to specify the ISO-code for the culture (language) to use for displaying the document. If not specified or if language customization has not been enabled on your account, the template or account default will be used. Currently supported cultures are: en-US (English - US), es-US (Spanish - US), fr-CA (French - Canada).
- An optional SignatureDeviceSupportEnabled indicator used to specify whether or not support will be enabled for signing written JotBlocks using an external signing device. If not specified or if signing device support has not been enabled at the account level, the template or account default will be used. It is recommended that this be left off unless it is explicitly known that an external signing device will be used to sign the document.
- An optional EnvelopeId indicator used to specify the unique identifier of the envelope the document should be added to. If specified, the document signing process will not be started immediately as it will only be triggered after the envelope is closed.
An optional TermsAndConditions element may also be passed within the Metadata element. In order to use this element, your AssureSign account must be configured to allow customization of the standard terms and conditions; this setting may only be modified by your AssureSign account representative. This element may contain an AdditionalComplianceStatement child element, an AdditionalAgreementStatement child element and an AdditionalExtendedDisclosures.
Information passed in the AdditionalComplianceStatement element will be appended to any default system or account terms that have been set that appear at the bottom of the signing splash page, and will replace any terms saved on the template. Information passed in the AdditionalAgreementStatement will be appended to any default system or account agreement terms, and will replace any agreement terms saved on the template; this information appears within a box requiring signatory action and the combined statement is followed by an “I Agree” check box. Information passed in the AdditionalExtendedDisclosures will be appended to the account extended disclosures box (this scrollable box is not displayed unless your account is configured to allow customization of the standard terms and conditions and some text has been specified to populate this area).
These elements should not be used merely for passing messages or additional information to the signer. Any information you pass here will be recorded as having been agreed to by the signatory. The standard non-customized AssureSign agreement statement starts with “By checking the box below, I agree that …”; therefore, additional phrases you may add to address specific legal requirements of a jurisdiction or type of document in the agreement section should conform to this first person statement or not interfere with the clarity of the overall statement.
Sample XML
The SOAP Action header is
The Parameter elements are either the parameters you created to fill JotBlocks , or parameters that fill workflow items , such as signer information.
Information will be returned that should be stored to allow future operations on the newly created document.
In particular, the Document ID and AuthToken will be required to request any further operations on an active document. The Document ID and AuthToken returned are in the form of a global unique identifier (GUID). A GUID is a 128 bit value returned as a 36 character string including embedded dashes; there are a variety of ways to store these values depending on your environment, and subsequent calls requiring these values will accept them in a number of supported formats. Sample XML returned by the Submit operation is presented here:
The DocumentResult should be checked for the presence of an Exceptions element, which may contain multiple DocumentException items.
