The submit/prepare operation provides a mechanism for pre-configuring a new envelope setup session. This allows applications to pass document, signer, and 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.
An envelope will not be finalized for workflow to start on it after calling submit/prepare. Either the envelope must be finalized in the Simple Setup user interface or by a call to /submit/{preparedEnvelopeID}.
The submit/prepare operation requires an active user session. Authentication should be performed using an API User via the method authentication/apiUserAuthentication.
Request
A typical submit/prepare operation request may include some of the following information:
Envelope
- Name: A human-readable name for the envelope
- OrderID: An optional extra identifier for your envelope.
- Signers: An optional array containing one or more Signer entities.
- NotificationRecipients: 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.
- Name: The full name of the signer.
- Email: 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.
- 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).
- SignatureStyle: An optional value indicating how you'd like the signer to sign. Can be one of the following values:
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
NotificationRecipient
- 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.
- Name: The full name of the recipient.
- Email: The email address of the signer (must be unique). SMS is not supported for custom recipients.
EmailNotification
- Name: A name to make it easy to identify the intended purpose and/or content of the email.
- 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. 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 All_Signers. To include signers for the current signing step, specify All_Signers_In_Step. 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:
- Envelope_Start
- Envelope_PreExpire
- Envelope_Expire
- Envelope_Complete
- Envelope_Cancel
- Envelope_Decline
- Signer_Feedback
- Signer_Auth_Failure
- Signer_Kba_Start
- Signer_Kba_Complete
- Step_Start (signing invitation notifications should be set on this step)
- Step_Complete
- On_Payment_Approved
- On_Payment_Declined
- On_Payment_Refunded
- On_Envelope_Landing_Visit
- 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 Step_Start or Step_Complete, the email notification will get set up for each step in the envelope.
Document
- Name: A human readable unique name for the document.
- FileName: The name with extension for the file to be uploaded.
- Data: The actual binary data for the file as a Base64 encoded string.
Sample Request:
Adjust the Host to match the location of your AssureSign account
POST /api/documentnow/v3.6/submit/prepare
Host: www.assuresign.net
Content-Type: application/json
Accept: application/json
Authorization: bearer allthetokenherexhj23kk5==
X-AS-UserContext: your@email.com:YourOrganizationContextID
{
"request": {
"content": {
"envelope": {
"name": "Example Envelope",
"orderID": "123456789"
},
"signers": [{
"label": "Signer 1",
"name": "John Doe",
"email": "john.doe@example.com",
"signatureStyle": "selectable",
"password": "6789",
"passwordPrompt": "Please enter the last 4 digits of your account #."
}
],
"notificationRecipients": [{
"label": "Sales",
"name": "Sales Department",
"email": "sales@example.com"
}
],
"emailNotifications": [{
"name": "Document Available to Sign",
"subject": "Document available to sign",
"body": "Please sign this document: **[Begin Signing]([Link - Document Signing])**",
"recipients": [
"All_Signers_In_Step"
],
"stage": "Step_Start"
}, {
"name": "Document Complete",
"subject": "Signing completed",
"body": "Congratulations! Signing is completed.",
"recipients": [
"All_Signers",
"Sales",
"Originator"
],
"stage": "Envelope_Complete"
}
],
"documents": [{
"name": "Document 1",
"file": {
"fileToUpload": {
"fileName": "document.pdf",
"data": ""
}
}
}
]
}
}
}
An even thinner example, where only the content of a PDF is uploaded and the expectation is the user will be redirected to AssureSign to mark up the document for signing is:
{
"request": {
"content": {
"documents": [
{
"file": {
"fileToUpload": {
"data": "BASE 64 FILE CONTENTS HERE",
"fileName": "Example.pdf",
"parseDocument": false
},
"extension": "pdf"
},
"name": "document 1",
}
]
}
}
}
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:
{
"messages": [],
"result": {
"preparedEnvelopeID": "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": "BAD_REQUEST", "summary": "Error parsing JSON", "details": [ "Error converting value ""startStep"" to type 'AssureSign.Domain.Core.Submission.Enums.Stage'. Path 'content.emailNotifications[0].stage', line 1, position 608.", "Path: content.emailNotifications[0].stage", "Item: stage" ]}A FORBIDDEN errorCode will be returned in the case that an invalid or expired token has been sent.
Redirecting to the setup page
This preparedEnvelopeId 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/<preparedEnvelopeId>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. The token generated by calling the authentication/apiUserAuthentication method 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/<preparedEnvelopeId>?ssoToken=<ssoTokenValue>The ssoToken expires after 30 seconds, so the call to retrieve the token should be performed when the redirection will take place.
