See behind the scenes
When the form is submitted we use the Envelopes: create API to send the signature request with the corresponding form information. We add Documents to sign and use a signerAttachmentTab to allow an optional image file to be added to the envelope. You can optionally add additional factors of authentication, such as AccessCode, Phone, or ID Check, and you can sign using embedded signing or remote signing.
This workflow uses the brandId property to apply a custom branding profile to the signing experience. It also contains multiple documents and demonstrates the Document Visibility feature. In this case Document Visibility is used to prevent the Applicant from seeing the Appraiser document until the envelope has completed.
The rules governing Document Visibility are as follows:
Text Tab with the following values:
recipientId: '2', documentId: '1', pageNumber: '1', xPosition: '0', yPosition: '0', value: '', locked: 'true'
Of the other Tabs, of special note is the "optional" attribute added to the SignerAttachment Tab:
"signerAttachmentTabs": [
{
"optional": "true",
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "Picture of Boat",
"anchorXOffset": "0",
"anchorYOffset": "40"
}
We are using Auto-Place to position our Tabs (notice the anchorString, anchorXOffset, and anchorYOffset strings.
Note: if you receive an error message when running this yourself, please view the README for settings your account may be missing.
To create and send the envelope we send an http POST request to:
POST /v2.1/accounts/{accountId}/envelopes
Click to view example request JSON
{
"status": "sent",
"emailSubject": "Sailboat Loan Application",
"emailBlurb": "Please sign the Loan application to start the application process.",
"enforceSignerVisibility": "true",
"brandId": "f157069c-3828-4073-a298-0bf5749b27bb",
"documents": [
{
"documentId": "1",
"name": "Application",
"fileExtension": "docx",
"documentBase64": "-- Base64-encoding document bytes are here --"
},
{
"documentId": "2",
"name": "Map",
"fileExtension": "png",
"documentBase64": "-- Base64-encoding document bytes are here --"
},
{
"documentId": "3",
"name": "Appraiser",
"fileExtension": "docx",
"documentBase64": "-- Base64-encoding document bytes are here --"
}
],
"recipients": {
"signers": [
{
"tabs": {
"signHereTabs": [
{
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "X:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
],
"initialHereTabs": [
{
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "X (initial):",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
],
"signerAttachmentTabs": [
{
"optional": "true",
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "Picture of Boat",
"anchorXOffset": "0",
"anchorYOffset": "40"
}
],
"fullNameTabs": [
{
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "Full Name:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
],
"emailTabs": [
{
"name": "Email",
"value": "-- RECIPIENT EMAIL HERE --",
"tabLabel": "Email",
"documentId": "1",
"recipientId": "1",
"pageNumber": "1",
"anchorString": "E-mail:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
]
},
"excludedDocuments": [
"2"
],
"name": "-- RECIPIENT NAME HERE --",
"email": "-- RECIPIENT EMAIL HERE --",
"recipientId": "1",
"clientUserId": "1001"
},
{
"tabs": {
"signHereTabs": [
{
"documentId": "3",
"recipientId": "2",
"pageNumber": "1",
"anchorString": "Appraiser Signature:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
],
"fullNameTabs": [
{
"documentId": "3",
"recipientId": "2",
"pageNumber": "1",
"anchorString": "Appraiser Name:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
],
"emailTabs": [
{
"name": "Email",
"value": "-- APPRAISER EMAIL HERE --",
"tabLabel": "Email",
"documentId": "3",
"recipientId": "2",
"pageNumber": "1",
"anchorString": "E-mail:",
"anchorXOffset": "100",
"anchorYOffset": "-2"
}
]
},
"name": "Caitlin Erlend",
"email": "-- APPRAISER NAME HERE --",
"recipientId": "2"
}
]
}
}
If Embedded Signing was selected we next use the EnvelopeViews: createRecipient API to generate a signing URL for the recipient. For this to work the clientUserId property must be set on the recipient when the envelope was sent during step 1.
Once the envelope is sent we save the envelope ID and Recipient information to our session then redirect to the /sign/embedded page. There we retrieve the envelope ID and recipient info from our session and create the recipient view by generating the URL and displaying in a full-width and full-height iframe.
To create the recipient view of the envelope we send an http POST request to:
POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient
Click to view example request JSON (the ReturnUrl information)
{
"clientUserId": "1001",
"userId": null,
"userName": "-- RECIPIENT NAME HERE --",
"email": "-- RECIPIENT EMAIL HERE --",
"recipientId": "1",
"returnUrl": "-- RETURN URL HERE --",
"pingUrl": null,
"pingFrequency": null,
"authenticationMethod": "email",
"assertionId": null,
"authenticationInstant": null,
"securityDomain": null
}