Tutorial: Using the DocuSign eSignature REST API with the REST Snap Pack and OAuth 2.0

DocuSign’s latest REST API version is 2.1 and also supports OAuth 2.0 authentication (replacing the legacy X-DocuSign-Authentication header-based auth).

DocuSign also provides free (no credit card neccessary) developer accounts to try out their API.

First, sign up for a DocuSign developer account here: https://go.docusign.com/o/sandbox

Next, in the DocuSign Apps and Keys page inside the DocuSign Settings application, you’ll see your account information, including API Username, API Account ID, and Account’s Base URI.

Click on the blue “Add App & Integration Key” button:

Provide an appropriate application name and click “Add”:

image

On the next page, your Integration Key (also known as a “Client ID”) will be displayed. Under the “Authentication” section, ensure the “Authorization Code Grant” radio button is enabled for a “User Application”. Then click on “Add Secret Key”:

image

IMPORTANT! Copy this secret key value immediately and paste it somewhere just for now - it will no longer be available to be used once you navigate away from this page.

Further down, under “Additional settings”, click the “Add URI” button and paste in the following value: https://elastic.snaplogic.com/api/1/rest/admin/oauth2callback/rest

image

Finally, click the “Save” button and you’ll return to the “Apps and Keys” section of the Developer admin console, where your application will now be visible.

Next, log into SnapLogic’s Designer web application, create a new pipeline and drag a REST GET Snap to the empty canvas. Switch to the “Account” tab and click the “Add Account” button:

Now it’s time to use the values from the DocuSign developer/integration web console - in another tab, click on the application you created within DocuSign and enter the following information:

Since we are using the DocuSign Demo Environment, we’ll be using the demo-specific account-d.docusign.com domain - the -d suffix is reserved for demo use.

Click the “Authorize” button towards the bottom to initiate the process to get an OAuth 2.0 access token.

Your web browser will send a request to the OAuth2 Endpoint URL (the Auth endpoint) - you may be asked to login and possibly to approve the application. After doing so, the request will redirect back to the SnapLogic platform (the redirect_uri where a new token request to the “OAuth2 Token” URL (the token endpoint) will automatically take place in the background and an access- and refresh tokens will be acquired.

If all goes well, the browser will navigate back to the SnapLogic Designer and your account will now have encrypted entries for the “Access-” and “Refresh token” fields, plus a timestamp value for the “Access token expiration” settings field.

Click “Apply” to save the account and we can now test that the access token we received is valid by making requests to the DocuSign eSignature REST API:

image

GET User Info

The first request will be to the User Info endpoint - https://account-d.docusign.com/oauth/userinfo

This endpoint will return environment data such as accountId, userId, and baseUrl - these are required to make any eSignature API call:

For Each Account

Since the response’s entity.accounts is an array, we can use the JSON splitter to operate on the account data that we will leverage in subsequent API calls:

GET Account Info

Finally, we can now make a call to the DocuSign eSignature REST API.

After the Splitter add another REST GET Snap, configure it with the same account used previously, and leverage the ability to refer to the input data ($base_uri, $account_id) to build the request URL to the demo.docusign.net API domain:

Validating and/or executing this Snap should result in a 200 OK response with a response body containing the metadata of the desired account, which can be further isolated with a Mapper mapping the $entity field to $:

And that should get your started. Consult the DocuSign REST API reference documentation to learn about other endpoints that can be used.

4 Likes