CreateEnvelope

Code Sample in C#

Note: Your agreement with AssureSign may cap the number of documents that may be attached per envelope.  Regardless of any explicitly designated cap, abuse of envelope operations may be cause for limiting your account activity.  Documents submitted explicitly to a named EnvelopeId are not parsed or processed until the CloseEnvelope operation is invoked.  Because of the relationship of documents within an envelope and the need to maintain their presentation order, the CloseEnvelope operation executes synchronously on associated documents in order of submission.  Therefore, submitting large amounts of documents within an envelope will be self performance-limiting.  For best performance, we do not recommend submitting more than 10 documents within an envelope.

The CreateEnvelope operation is used to create a new document envelope to which one or more related documents may be added.

This operation may be executed using either the W3C standard Message Transmission Optimization Mechanism (MTOM) or by converting attachments to Base64 encoded strings and including them in the XML. Using MTOM, the attachments are passed in their original raw binary form using XML-binary Optimized Packaging (XOP). Non-MTOM enabled clients may use the process of encoding the attachment contents and including the data as additional elements in the XML.

The CreateEnvelope operation requires knowledge of the following:

• The AssureSign account ContextIdentifier (this is exposed in the AssureSign administrative application account settings and serves to provide some security to the transaction)
• The UserName of the AssureSign user that will be the owner of the envelope within AssureSign
• The desired user-defined EnvelopeName for the document envelope (for reporting purposes)
• The desired WorkflowType for the document envelope. Possible options include
  • Parallel: all documents will be available for signing at the same time and
  • Sequential: only one document will be available for signing at a time
• DeclineBehavior, the desired behavior for signatory-initiated declining of signing. Possible options include
  • DeclineAll: all incomplete documents in the envelope are declined and
  • DeclineSingle: only the selected document(s) are declined and signing will still be available for other incomplete documents in the envelope
• ViewBehavior, the desired behavior for controlling which documents are available for a signatory to view when accessing an envelope for signing. Possible options include
  • ViewSignatoryOnly: the signatory will only be able to view a document if they are configured as a signer for that document and
  • ViewAll: the signatory will be able to view any documents in the envelope.

Additional attributes may also be optionally specified with the CreateEnvelope operation to control other properties and behaviors of the envelope:

• An EnvelopeTemplateId may be optionally specified to set the envelope template that will be used for defining envelope notifications for events that occur during the envelope life-cycle.
• A RedirectUrl may be optionally specified to provide a URL that signers will be redirected to after signing when they have no other documents in the envelope they can currently sign. Note: if a URL is specified here, it will supersede any other redirect URLs specified elsewhere in the application (such as a default account redirect URL, etc.)
• An EnvelopePassword may be optionally provided to ensure that a password will be required in order to access any of the completed documents in the envelope.
• An ExpirationDate may be optionally specified to indicate the date when the envelope (and all contained documents) will expire. If not specified, the expiration date will be automatically set based on the default expiration period for the account.
• an optional EnvelopeOrderNumber, which is designed to provide you a way to store your unique order number or key to identify the document.  This may be retrieved via the [Envelope Order ID] merge field.

One or more Addendums (also known as envelope attachments) may also be optionally included with the request to create an envelope. These addendums are non-signable and simply provide a way to present additional materials to signers during signing. While multiple addendums may be specified, please note that the maximum size of any request cannot exceed 30 MB. The following attributes may be specified for an EnvelopeAttachment contained within an Attachments element:

• A Name must be provided to uniquely identify the addendum within the envelope.
• A Description may optionally be specified to provide an extended description of the addendum.
• A file Extension must be provided to indicate the file extension of the addendum (PDF, DOC, DOCX, etc.)

Sample XML

Sample condensed XML using the MTOM method is presented here:

<?xml version="1.0" encoding="utf-8"?> 
<CreateEnvelope xmlns="https://www.assuresign.net/Services/DocumentNOW/Envelopes"> 
    <CreateEnvelopeRequest ContextIdentifier="06C4A84A-693C-46CB-8DF2-40A8215AA056" UserName="georgeuser@company.com" EnvelopeName="John Doe Contract Package" EnvelopeTemplateId="0FF4ACDD-A422-AAF8-78A7-1B119AC987AB" WorkflowType="Sequential" DeclineBehavior="DeclineAll" ViewBehavior="ViewSignatoryOnly"> 
        <Attachments> 
            <EnvelopeAttachment Name="Addendum (PDF)" Description="A PDF document that will be available for signers to view but not sign." Extension="pdf"> 
                <FileData> 
                <xop:Include href="cid:http%3A%2F%2Ftempuri.org%2F1%2F633584454199417714" xmlns:xop="http://www.w3.org/2004/08/xop/include"/> 
                </FileData> 
            </EnvelopeAttachment> 
        </Attachments> 
    </CreateEnvelopeRequest> 
</CreateEnvelope>

The SOAP Action header is

https://www.assuresign.net/Services/DocumentNOW/Envelopes/IEnvelopeService/CreateEnvelope

Using either the MTOM or encoded text method, information will be returned that should be stored to allow future operations on the newly created envelope. In particular, the EnvelopeId and AuthToken will be required to request any further operations on an active envelope, and will be needed in particular to call CloseEnvelope. The EnvelopeId and AuthToken are returned 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.

Also worth noting about the response is that a StaleDate property will be returned which is an AssureSign system-assigned date/time value indicating the point by which the envelope must be closed via a call to CloseEnvelope before it will be considered stale (i.e. stale envelopes are cleaned up and placed in an unavailable state).

Sample XML returned by the CreateEnvelope operation is presented here:

<?xml version="1.0" encoding="utf-8"?> 
<CreateEnvelopeResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Envelopes"> 
    <CreateEnvelopeResult EnvelopeId="2CE11EF1-8938-DD11-8735-00065B8CE99B" AuthToken="8CC9A84B-693C-46CC-4342-40A8215AD76A" ExpirationDate="2013-08-12" StaleDate="2012-01-12T13:54:42.3538796Z" /> 
</ CreateEnvelopeResponse>

The CreateEnvelopeResult should be checked for the presence of an Exceptions element, which may contain multiple EnvelopeException items.

Now that you've created an envelope, you can add documents to it by using one of the DocumentNOW methods used for submitting documents, listed here. Once you are done adding documents to your envelope, you can use CloseEnvelope to begin the signing process.