Follow

Submit/Prepare

Last updated 2017-12-08 21:19:01 UTC

The submit/prepare operation provides a mechanism for pre-configuring a new envelope setup session. This allows applications to pass document, signer, and email notifications to AssureSign in advance, so that when the originator pulls up that envelope setup session all they will need to do is mark up the document(s) and send.

This operation will be one of the first methods available in our new V3 DocumentNOW API. This new version of our API is being redesigned from the ground up to be more robust and to allow easier integration from a variety of platforms. We will be augmenting our new V3 API over time to incorporate the functionality currently available in our V1 and V2 API as well as to provide new functionality such as this new Prepare operation.

Request

The Prepare operation requires an active user session. Similar to other DocumentNOW V3 operations, authentication can be handled in several different ways:

  1. Set the Authorization header to Basic plus the username:password as a Base64 encoded string. For example:
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  2. Set the Authorization header to X-AS-UserSessionToken plus the user session token returned from the authentication/credentials operation. For example:
    Authorization: X-AS-UserSessionToken VGhpcyB3b3VsZCBiZSB0aGUgY29udGVudHMgb2YgdGhlIHRva2Vu

From a payload perspective, a typical Prepare operation request will include the following information:

Envelope

  • Name: A human-readable name for the envelope
  • Signers: An optional array containing one or more Signer entities.
  • CustomRecipients: An optional array containing one or more non-signer email recipients.
  • EmailNotifications: An optional array containing one or more adhoc email notifications (i.e. not tied to any email designs).
  • Documents: An array containing one or more documents to include in the envelope.

While Signers and EmailNotifications are optional, when not passed in they will need to be created in the envelope setup interface

Signer

  • Label: A unique identifier for the signer. This could be a number, a GUID, an email address or any other string identifier that is unique to this signer.
  • FullName: The full name of the signer.
  • EmailAddress: The email address of the signer (must be unique).
  • MobilePhone: The mobile phone number of the signer (must be unique).  This may be used only when SMS notifications are enabled.
  • Authentication: An optional SignerAuthentication object.
  • SignatureStyle: An optional value indicating how you'd like the signer to sign. Can be one of the following valus:
        Drawn: the signer will draw their signature with the mouse or an external signing device
        Typed: the signer will type their signature
        Selectable: the signer will be able to choose to do one of the previous

SignerAuthentication

  • Password: A pre-shared password used to help ensure that only the intended signer has access to sign documents in the envelope.
  • PasswordPrompt: An optional prompt to help signers know what to enter as a password (last 4 of social, etc).

CustomRecipient

  • Label: A unique identifier for the custom recipient. This could be a number, a GUID, an email address or any other string identifier that is unique to this recipient.
  • FullName: The full name of the signer.
  • EmailAddress: The email address of the signer (must be unique).  SMS is not supported for custom recipients.

Notification

  • Type: An enumeration value indicating the type of notification this is. Accepted values are:
    • email
    • sms
  • Name: A name to make it easy to identify the intended purpose and/or content of the email or SMS.
  • for Type email, the following may be specified:
    • Subject: The subject line of the email.
    • Body: The full contents of the email body as plain text or Markdown. This content may include all of the standard AssureSign merge fields that are available for use in email designs.
  • Recipients: An array of one or more strings identifying the intended recipient(s) for the email or SMS text. To include a signer or custom recipient, provide the appropriate Label or FullName . To include the originator, specify the text originator. To include all signers, specify AllSigners. To include signers for the current signing step, specify AllSignersInStep.  Note that custom recipients are not supported for SMS notifications.
  • Stage: An enumeration value indicating the stage in the envelope workflow when the email should be sent.  Valid Stage values are:
    • envelopeStart
    • envelopePreExpire
    • envelopeExpire
    • envelopeComplete
    • envelopeCancel
    • envelopeDecline
    • signerFeedback
    • signerAuthFailure
    • signerKbaStart
    • signerKbaComplete
    • stepStart (signing invitation notifications should be set on this step)
    • stepComplete
  • Step: For email notifications with a Stage of beforeStep* or afterStep, this step # will identify which step the email notification will be associated with. If a Step is not provided but the Stage is beforeStep or afterStep, the email notification will get set up for each step in the envelope.

Document

  • Name: A human readable unique name for the document.
  • Data: The actual binary data for the file as a Base64 encoded string.
  • DataType: The file type for the document such as pdf, doc, docx, etc.

Sample Request

Adjust the Host to match the location of your AssureSign account

POST /api/documentnow/v3.0/submit/prepare
Host: www.assuresign.net
Content-Type: application/json
Accept: application/json
Authorization: X-AS-UserSessionToken eyJ2YWxpZFVudGlsIjoxNDY3MTYzNTcwNDAwLjcyMjksImFjY291bnRJZCI6IjFhN2Q5YzE2LTA5OTQtNGVlYS04ODE0LWNkZTlhOWMyNTNiNiIsImVtYWlsQWRkcmVzcyI6Im1jaHlub3dldGhAYXNzdXJlc2lnbi5jb20iLCJmdWxsTmFtZSI6Ik1pa2UgQ2h5bm93ZXRoIiwidXNlcklkIjoiMzYzMzQ1NTMtNGI1Yy00MDE4LWIzNDItYTYyNzAwYzc0YjYyIiwibmV2ZXJFeHBpcmUiOmZhbHNlLCJzaWduYXR1cmUiOiJIYUIxOGo4bG9XMHRfdUpzYnVnTERZWVVOSkpLY0JsZWw0dENjY1RiM2tFIn0

{
    "request": {
        "envelope": {
            "name": "Example Envelope",
            "signers": [{
               "label": "Signer 1",
               "fullName": "John Doe",
               "emailAddress": "john.doe@example.com",
               "authentication": {
                   "password": "6789",
                   "passwordPrompt": "Please enter the last 4 digits of your account #."
               }
            }],
            "customRecipients": [{
                "label": "Sales",
                "fullName": "Sales Department",
                "emailAddress": "sales@example.com"
            }],
            "notifications": [{
                "type": "email",
                "name": "Document Available to Sign",
                "subject": "Document available to sign",
                "body": "Please sign this document: **[Begin Signing]([Link - Document Signing])**",
                "recipients": [
                    "AllSignersInStep"
                ],
                "stage": "stepStart"
            }, {
                "name": "Document Complete",
                "subject": "Signing completed",
                "body": "Congratulations! Signing is completed.",
                "recipients": [
                    "AllSigners", 
                    "Sales", "Originator"
                ],
                "stage": "envelopeComplete"
            }],
            "documents": [{
                "name": "Document 1",
                "data": "<Base64 encoded file data>",
                "dataType": "pdf"
            }]
        }
    }
}

Response

If the request is successful, the operation will return a simple result that will include an id property. This id is essentially a Session ID that uniquely identifies the prepare session.

Sample Response:

{
    "result": {
        "id": "8d045644-f239-456f-a0bc-a63201428211"
    }
}

If the request is formatted incorrectly or an error occurs during processing, an error response will be returned which will include an errorCode and a summary of the error.

Sample Error Response:

{
    "errorCode": "INTERNAL_SERVER_ERROR",
    "summary": "An error occurred processing the document data"
}

A FORBIDDEN errorCode will be returned in the case that an invalid or expired token has been sent.

Redirecting to the setup page

This id returned in the response can then be used to construct a URL that will open the envelope setup interface for the user with the provided data pre-populated in the workspace. The constructed URL should be in the form:

https://www.assuresign.net/ui/simpleSetup/<id>

You will need to modify the root URL to be the location of your AssureSign account.

Note that the user will be prompted to enter their credentials and log in if they do not have an active session.  However, it is possible to eliminate the need for the manual entering of credentials at this step by making a call to the authentication/sso operation.  If a X-AS-UserSessionToken was generated by calling the authentication/credentials method as shown above (which token grants access to make API calls), that token may be further used to generate the ssoToken that can be appended to the above URL.  For example, the final URL may be modified with the token added at the end like this:

https://www.assuresign.net/ui/simpleSetup/<id>?ssoToken=<ssoTokenValue>

 

 

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

0 Comments

Article is closed for comments.