DocuSign

Overview

Quickly and easily create, manage, and send eSignatures using the DocuSign connected system. DocuSign envelopes can contain one or more documents, the fields in the document, recipient info, delivery progress, sender information, security, and more.

For information that pertains to all connected systems, see Connected System Object.

Properties

Three forms of authentication are available for DocuSign: Authorization Code Grant (per user), JWT Grant (single system login), and Basic Authentication (deprecated legacy feature for single system login).

Basic Authentication

Uses the DocuSign Legacy Header Authentication Method, which requires a single DocuSign user's credentials to authenticate. See DocuSign documentation for more details.

Note: Since DocuSign is removing support for basic authentication on October 5, 2022, developers must modify any DocuSign connected systems that use Basic Authentication to use the newly supported JWT Grant authentication type before that date.

A DocuSign connected system using the Legacy Header Authentication Method has the following properties:

Field	Description
Name	Required The name of the connected system. Use a name that will uniquely identify this connection to the external system.
Description	Supplemental information about the connected system that is displayed in the objects grid of some Designer views and when selecting the system in an integration object.
Instance URL*	Required This URL is used to configure your integration object and when executing your operations. For example: `https://demo.docusign.net`
API Account ID*	Required To find the API Account ID, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys.
API Username*	Required The username used to sign into the provided DocuSign instance. To find the API Username, go to the Account screen in DocuSign. Under Users And Groups, click Users and select a user.
Password*	Required/Sensitive The password used to sign into the provided DocuSign instance.
Integration Key*	Required To find the Integration Key, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys and select your App Name.

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.

screenshot of the Basic Authentication method selected in a DocuSign connected system object

Authorization Code Grant

Uses the DocuSign OAuth 2.0 Authentication Method, where each Appian user will be required to sign in to their DocuSign account to authenticate. You must provide users a way to authenticate using OAuth 2.0. See DocuSign documentation for more details.

Note: The DocuSign connected system doesn't use refresh tokens with the Authorization Code grant. The end user will have to reauthorize each time that the access token expires.

A DocuSign connected system using Authorization Code Grant has the following properties:

Field	Description
Name	Required The name of the connected system. Use a name that will uniquely identify this connection to the external system.
Description	Supplemental information about the connected system that is displayed in the objects grid of some Designer views and when selecting the system in an integration object.
Instance URL*	Required This URL is used to configure your integration object and when executing your operations. For example: `https://demo.docusign.net`
API Account ID*	Required To find the API Account ID, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys.
Integration Key*	Required To find the API Username, go to the Account screen in Docusign. Under Users And Groups, click Users and select a user.
Secret Key*	Required/Sensitive From the Apps and Keys page for your app, under Authentication, select Authorization Code Grant and click ADD SECRET KEY.
DocuSign Environment*	Required This is either DocuSign Development, `https://account-d.docusign.com`, or Production, `https://account.docusign.com`.

Click AUTHORIZE to use the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

screenshot of the Authorization Code authentication method selected in a DocuSign connected system object

JWT Grant

Uses JWT Grant authentication, which is the OAuth 2.0 flow that DocuSign uses for service integrations. This replaces Basic Authentication, which DocuSign is removing support for on October 5, 2022. See DocuSign documentation for more details on how to configure DocuSign to work with the JWT Grant.

A DocuSign connected system using the JWT Grant has the following properties:

Field	Description
Name	Required The name of the connected system. Use a name that will uniquely identify this connection to the external system.
Description	Supplemental information about the connected system that is displayed when selecting the system in the integration designer and in the application contents grid.
API Account ID*	Required To find the API Account ID, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys.
API Username*	Required The username of a DocuSign user with permission to impersonate end users on a long-term basis. For example, a service integration might use an HR alias or manager’s account credentials to send onboarding documents whenever a new employee is hired by a company. To find the API Username, go to the Account screen in DocuSign. Under Users And Groups, click Users and select a user.
Integration Key*	Required To find the Integration Key, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys and select your App Name.
Private RSA Key*	Required/Sensitive The private key in an RSA keypair used for JWT authentication. To generate a Private RSA Key, go to the Account screen in DocuSign. Under Integrations, click Apps and Keys. Then select your App Name. Finally, under Service Integration, click Generate RSA. Note that when using an import customization file to set a Private RSA Key, you will need to replace the nextline characters after `-----BEGIN RSA PRIVATE KEY----` and before `-----END RSA PRIVATE KEY-----` with spaces. However, when pasting a Private RSA Key into the connected system interface, this will be done for you automatically.
DocuSign Environment*	Required This is either DocuSign Development, `https://account-d.docusign.com`, or Production, `https://account.docusign.com`.

Click TEST CONNECTION to use the provided configuration information to fetch an access token.

/images/jwt for docusign

Automating property updates

This object's properties can also be updated programmatically using the Update Connected System endpoint. This lets you change passwords, API keys, and other values without needing to sign in to Appian.

The following properties can be included in the JSON request body of the PATCH /connected-system/<UUID> call.

Authentication Type	Available Properties
Basic Auth	instanceUrl, accountId, userId, password, integrationKey
Auth Code Grant	instanceUrl, accountId, integrationKey, clientSecretKey, environmentKey
JWT Grant	instanceUrl, accountId, userId, integrationKey, privateRsaKey, environmentKey

Operations

Name	Description	Type
Send Document for eSignature	Sends a document to a specified recipient for eSignature	WRITE
Create and Send Envelope	Creates and sends an envelope for eSignature or creates a draft envelope	WRITE
Get Envelope Definition	Gets envelope information for a specified envelope	READ
List Envelopes	Gets a list of envelopes that match specified search parameters	READ
Update Envelope Definition	Modifies envelope definitions including status	WRITE
List Documents of an Envelope	Gets a list of all documents associated with a specified envelope	READ
Upload New Documents to an Envelope	Adds or updates documents to a specified envelope	WRITE
Download Document from an Envelope	Gets a document from a specified envelope and saves it into Appian	WRITE
List Audit Events of an Envelope	Gets envelope audit events for a specified envelope	READ
Generate the Recipient Signing URL	Gets a pre-authenticated URL to allow a user to eSign from Appian	WRITE

Send Document for eSignature

Sends a document to a specified recipient for eSignature.

Send Document for eSignature is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Send Document for eSignature operation selected in a DocuSign integration object

Create and Send Envelope

Creates and sends an envelope for eSignature or creates a draft envelope.

See the examples below of how to set up your DocuSign envelope.

Note: If you're updating a DocuSign connected system that previously used Basic Authentication to use JWT Grant authentication instead, you should pay special attention to the Create and Send Envelope operation. If a single DocuSign connected system had multiple Create and Send integrations with different values for the From dropdown (which isn't present for integrations using the JWT Grant), you will need to create a new connected system for each From value. See the DocuSign documentation on Send on Behalf Of functionality for more information.

Create and Send Envelope is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Create and Send Envelope operation selected in a DocuSign integration object

Get Envelope Definition

Gets envelope information for a specified envelope.

screenshot of the Get Envelope Definition operation selected in a DocuSign integration object

List Envelopes

Gets a list of envelopes that match specified search parameters.

screenshot of the List Envelopes operation selected in a DocuSign integration object

Update Envelope Definition

Modifies envelope definitions including status.

Update Envelope Definition is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Update Envelope Definition operation selected in a DocuSign integration object

List Documents of an Envelope

Gets a list of all documents associated with a specified envelope.

screenshot of the List Documents of an Envelope operation selected in a DocuSign integration object

Upload New Documents to an Envelope

Adds or updates documents to a specified envelope.

Upload New Documents to an Envelope is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Upload New Documents to an Envelope operation selected in a DocuSign integration object

Download Document from an Envelope

Gets a document from a specified envelope and saves it into Appian.

Download Document from an Envelope is a WRITE type Integration. To protect against duplicate document creation, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Download Document from an Enveloper operation selected in a DocuSign integration object

List Audit Events of an Envelope

Gets envelope audit events for a specified envelope.

screenshot of the List Audit Events of an Envelope operation selected in a DocuSign integration object

Generate the Recipient Signing URL

Gets a pre-authenticated URL to allow a user to eSign from Appian.

Generate the Recipient Signing URL is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

screenshot of the Generate the Recipient Signing URL operation selected in a DocuSign integration object

DocuSign envelope examples

Request signature on single document by email

This example shows an integration configuration that includes:

A single PDF document to be signed
One tab positioned using anchor text
One recipient
For more information, see DocuSign examples

See full Envelope Definition below.

Envelope definition

a!toJson(
  {
    "emailSubject": "Please sign the NDA",
    "recipients": {
      "signers": {
        {
          "email": "the_nda_signer@example.com",
          "name": "Darlene Petersen",
          "recipientId": "1",
          "routingOrder": "1",
          "tabs": {
            "dateSignedTabs": {
              {
                "anchorString": "signer1date",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Date Signed",
                "recipientId": "1",
                "tabLabel": "date_signed"
              }
            },
            "fullNameTabs": {
              {
                "anchorString": "signer1name",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Full Name",
                "recipientId": "1",
                "tabLabel": "Full Name"
              }
            },
            "signHereTabs": {
              {
                "anchorString": "signer1sig",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "0",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "signer1sig"
              }
            }
          }
        }
      }
    }
  }
)
Copy

Multiple documents and tabs, signer and CC recipients

This example shows an integration configuration that includes:

Multiple documents.
Multiple tabs including signing, fullName, dateSigned, and text tabs.
Tabs positioned using anchor text.
Two recipients, a signer and a cc recipient.

For more information, see DocuSign examples.

See full expressions for Envelope Definition and Documents.

docusign-examples-DocuSign_MultipleDocumentsTabsSignerCC.png

Envelope Definition

a!toJson(
  {
    "emailSubject": "Please sign the house documentation package",
    "recipients": {
      "carbonCopies": {
        {
          "email": "cody_vigil@worldwidecorp.example.com",
          "name": "Cody Vigil",
          "recipientId": "2",
          "routingOrder": "2"
        }
      },
      "signers": {
        {
          "email": "darlene_petersen@newco.example.com",
          "name": "Darlene Petersen",
          "recipientId": "1",
          "routingOrder": "1",
          "tabs": {
            "dateSignedTabs": {
              {
                "anchorString": "signer1date",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Date Signed",
                "recipientId": "1",
                "tabLabel": "date_signed"
              },
              {
                "documentId": "2",
                "fontSize": "Size12",
                "name": "Date Signed",
                "pageNumber": "1",
                "recipientId": "1",
                "tabLabel": "doc3_date_signed",
                "xPosition": "89",
                "yPosition": "100"
              }
            },
            "fullNameTabs": {
              {
                "anchorString": "signer1name",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Full Name",
                "recipientId": "1",
                "tabLabel": "Full Name"
              }
            },
            "signHereTabs": {
              {
                "anchorString": "signer1sig",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "0",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "signer1sig"
              },
              {
                "documentId": "2",
                "name": "Please sign here",
                "optional": "false",
                "pageNumber": "1",
                "recipientId": "2",
                "scaleValue": 1,
                "tabLabel": "signer1_doc2",
                "xPosition": "89",
                "yPosition": "40"
              },
              {
                "anchorString": "Client Signature",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "-4",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "doc3_client_sig"
              }
            },
            "textTabs": {
              {
                "anchorString": "signer1company",
                "anchorYOffset": "-8",
                "fontSize": "Size12",
                "name": "Company",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company"
              },
              {
                "anchorString": "Client Name",
                "anchorYOffset": "-38",
                "fontSize": "Size12",
                "name": "Company",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company"
              },
              {
                "documentId": "3",
                "fontSize": "Size10",
                "name": "Company",
                "pageNumber": "1",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company",
                "xPosition": "145",
                "yPosition": "195"
              }
            }
          }
        }
      }
    }
  }
)
Copy

Documents

{
  documents: {
    {
      documentId: 1,
      name: "NDA",
      appianDocument: todocument(1234)
    },
    {
      documentId: 2,
      name: "House",
      appianDocument: todocument(5678)
    },
    {
      documentId: 3,
      name: "contractor_agreement",
      appianDocument: todocument(9012)
    }
  }
}
Copy

Feedback

Was this page helpful?

DocuSign

OverviewCopy link to clipboard

PropertiesCopy link to clipboard

Basic AuthenticationCopy link to clipboard

Authorization Code GrantCopy link to clipboard

JWT GrantCopy link to clipboard

Automating property updatesCopy link to clipboard

OperationsCopy link to clipboard

Send Document for eSignatureCopy link to clipboard

Create and Send EnvelopeCopy link to clipboard

Get Envelope DefinitionCopy link to clipboard

List EnvelopesCopy link to clipboard

Update Envelope DefinitionCopy link to clipboard

List Documents of an EnvelopeCopy link to clipboard

Upload New Documents to an EnvelopeCopy link to clipboard

Download Document from an EnvelopeCopy link to clipboard

List Audit Events of an EnvelopeCopy link to clipboard

Generate the Recipient Signing URLCopy link to clipboard

DocuSign envelope examplesCopy link to clipboard

Request signature on single document by emailCopy link to clipboard

Envelope definitionCopy link to clipboard

Multiple documents and tabs, signer and CC recipientsCopy link to clipboard

Envelope DefinitionCopy link to clipboard

DocumentsCopy link to clipboard

FeedbackCopy link to clipboard