Introduction
The Adobe Sign Workflow design is intended to make it easier for a user to send agreements for signing.
Specifically, each participant is described by a “label” in the Workflow design which would guide the Workflow user to enter the correct email addresses of participants. These labels are more descriptive than “signer1” and “signer2.”
Sign Library Documents for the agreement can also be defined in the Workflow design, making it unnecessary for the user to define these or upload these each time the agreement is sent.
Finally, unlike a regular Send operation, field values may be entered as part of the send operation, which values will be pre-filled on a form that is to be signed.
But what if you want to invoke a Sign Workflow design using the API? The method for doing this with v6 of the Sign API is not obvious until you’ve successfully done it once.
Because a Workflow design typically guides the user through entering email addresses, defining documents to be included and providing pre-fill values for fields on the form to be signed, you must accomplish these steps through the API. This article walks you through the procedure for doing just that and provides a skeleton JSON object for use in building an Agreements API call.
Overview
Basically, the procedure is to perform three API calls. These steps are detailed in the rest of this article.
- Get a list of Workflow designs available. You will iterate this list to find the id of the Workflow design you wish to start.
- Use the id thus obtained to retrieve details about the Workflow design, such as labels used for defining participants, and field names of form fields that must be pre-filled.
- Create and send an agreement using the details in the Workflow design such as labels and form field names.
Step 1: Get a List of Workflow Designs
Simply use this API call: GET /workflows
That returns a JSON payload similar to this:
{
"userWorkflowList": [
{
"id": "CBJCHBCAABAARJTRAPnYQx-kuL_XVL7NMsen2HBwBrMr",
"created": "2020-05-25T19:32:29Z",
"name": "3a9cbffd6a0014189a0f6e6ed0dd2075",
"displayName": "Applicant PII Request",
"status": "ACTIVE",
"scope": "ACCOUNT",
"description": "This workflow will send a package”
},
{
"id": "CBJCHBCAABAAhOSDIyhgH3JTdKvsftuLfI7_dGpz6OlE",
"created": "2020-05-26T17:43:51Z",
"name": "8d2c2aaeb2ba6949002cbc7de990e835",
"displayName": "Contract for Signing by Mayor",
"status": "ACTIVE",
"scope": "ACCOUNT",
"description": "Sends a contract for signing"
}
]
}
What you must do is iterate through the objects in the “userWorkflowList”, until you find the “displayName” of the workflow design that you wish to start. Upon finding that, get the “id” of the workflow design.
Step 2: Get Details About the Chosen Workflow
Now execute this API call: GET /workflows/{workflowId}
Provide the “id” obtained from Step 1 as the {workflowId}.
That returns a payload containing JSON similar to this:
{
"name": "3a9cbffd6a0014189a0f6e6ed0dd2075",
"displayName": "Applicant PII Request",
"created": "2020-09-16T12:10:11Z",
"modified": "2020-09-16T12:10:11Z",
"status": "ACTIVE",
"scope": "ACCOUNT",
"description": "Please complete and send this workflow",
"agreementNameInfo": {
"required": true,
"defaultValue": "Papers To Sign",
"editable": true,
"visible": true
},
"messageInfo": {
"required": true,
"defaultValue": "Please sign the papers.",
"editable": true,
"visible": true
[. . .]
"fileInfos": [
{
"name": "document1",
"label": "Deferment Application",
"required": true,
"workflowLibraryDocumentSelectorList": [
{
"workflowLibDoc": "3AAABLblqZhCo1 ... z8ZrCXx0_EG8-P",
"label": "[DEMO USE ONLY] Deferment_application",
"sharingMode": "ACCOUNT",
"templateTypes": [
"DOCUMENT"
],
"modifiedDate": "2020-09-16T12:05:56Z"
}
]
}
],
"recipientsListInfo": [
{
"name": "signer1",
"label": "This is the label for the first signer.",
"defaultValue": "",
"minListCount": 1,
"maxListCount": 1,
"editable": true,
"visible": true,
"allowfax": false,
"allowSender": true,
"authenticationMethod": "NONE"
},
{
"name": "signer2",
"label": "This is the label for the second signer.",
"defaultValue": "",
"minListCount": 1,
"maxListCount": 1,
"editable": true,
"visible": true,
"allowfax": false,
"allowSender": true,
"authenticationMethod": "NONE"
}
],
"ccsListInfo": [
{
"name": "observers",
"label": "Cc",
"defaultValues": [
carmank@lawrick.com
],
"required": false,
"editable": false,
"visible": true,
"minListCount": 0,
"maxListCount": 500
}
],
"passwordInfo": {
"required": false,
"visible": false,
"defaultValue": "",
"editable": false
},
"mergeFieldsInfo": [
{
"fieldName": "firstName",
"displayName": "Applicant First Name",
"defaultValue": "Carman",
"editable": true,
"visible": true,
"required": true
},
{
"fieldName": "lastName",
"displayName": "Applicant Last Name",
"defaultValue": "Lawrick",
"editable": true,
"visible": true,
"required": true
}
]
}
Step 3: Build and Submit Your Request JSON
Start with the following skeleton JSON, and fill it with details as described below. Some details (especially the labels) come from the JSON obtained in Step 2.
{
"name": "My API Invoked Agreement",
"signatureType": "ESIGN",
"state": "IN_PROCESS",
"message": "Please sign the papers.",
"workflowId": "CBJCHBCAA ... AWkMJga",
"fileInfos": [
{
"label": "Deferment Application",
"libraryDocumentId":"3AAABL … Xx0_EG8-P"
}
],
"participantSetsInfo": [
{
"label": "This is the label for the first signer.",
"memberInfos": [
{
"email": "johndoeski@mailinator.com"
}
],
"order": 1,
"role": "SIGNER"
},
{
"label": "This is the label for the second signer.",
"memberInfos": [
{
"email": "janedoeski@mailinator.com"
}
],
"order": 2,
"role": "SIGNER"
}
],
"mergeFieldInfo":[
{
"defaultValue": "John",
"fieldName": "firstName"
},
{
"defaultValue": "Doeski",
"fieldName": "lastName"
}
]
}
- Give your agreement a name, in the "name" field of the JSON object we're building. This is the name used in the subject line of emails to participants.
- Set the agreement "signatureType", such as "ESIGN"
- Set the agreement state, such as "IN_PROCESS" or "DRAFT"
- Optionally, set the “message” from the workflow details “messageInfo” and “defaultValue”
- Set the "workflowId" to the same one obtained in Step 1, above
- In the workflow details, look at the "fileInfos" array. For each item listed copy the exact "label" and "workflowLibDoc" id into the "fileInfos" array you're building.
NOTE: in the "fileInfos" array in the workflow details, there are TWO "label"s provided. The one you want is in the outer JSON object, not the one in the inner JSON object (called "workflowLibraryDocumentSelectorList")
- This is where you specify the participants in the agreement. You provide an email address and label for each participant defined in the Sign Workflow design.
In the workflow details, look at the "recipientsListInfo" array. Copy the "label" to the object in the "participantSetsInfo" object. Enter the email address in the "memberInfos" array.
- Set the "order" number and the "role" for the participant. The "role" is not present in the workflow details in Step 2. You must get this by looking at the Sign Workflow designer.
- In the workflow details, look at the "mergeFieldsInfo" array. For each object in the array, copy the "fieldName" property and "defaultValue" property to an object in the "mergeFieldInfo" array that you're building.
You now have a JSON body to submit to the POST /agreements API endpoint.
Conclusion
While it may not be obvious how to start a Sign Workflow from the API, using the skeleton JSON and getting it right once can make the technique trivial.
More on Adobe Sign:
https://acrobat.adobe.com/us/en/sign.html
.svg)
.svg)
.svg)