DocuSign eSignature API Client

6.1.0 · active · verified Sat Apr 11

The DocuSign eSignature REST API client for Python provides convenient access to the DocuSign eSignature API. It allows developers to integrate e-signature capabilities into their applications, managing envelopes, documents, and recipients. The current version is 6.1.0, with ongoing development and regular releases to reflect API updates and improvements.

Warnings

gotcha The DocuSign API server (e.g., `demo.docusign.net/restapi` or `naX.docusign.net/restapi`) and the OAuth authentication server (e.g., `account-d.docusign.com` or `account.docusign.com`) use distinct base URLs. Misconfiguring `config.host` for API calls or the `auth_host` parameter in OAuth token requests can lead to authentication failures or API connection issues.
Fix: Ensure `config.host` is set to the correct API base URL (including `/restapi` and API version, typically `v2.1`), and the `auth_host` parameter in JWT/OAuth methods points to the correct authentication server. Use 'account-d.docusign.com' for demo/sandbox environments and 'account.docusign.com' for production.
gotcha JWT Grant authentication requires precise setup: `client_id` (integration key), `impersonated_user_id` (GUID of the user to impersonate), `private_key_bytes` (the raw PEM private key from your integration app), and correct `scopes` (e.g., 'signature', 'impersonation'). Common errors include 'consent required' (the impersonated user hasn't granted consent to the integration key) or 'invalid_grant' (incorrect client ID, user ID, private key, or scopes).
Fix: Verify all JWT parameters match your DocuSign integration key settings in Admin Console. Ensure the impersonated user has granted consent for your integration key in their DocuSign account. Load the private key as raw PEM bytes (e.g., `open('private_key.pem', 'rb').read()`).

Install

pip install docusign-esign Install latest version

Imports

ApiClient
```
from docusign_esign import ApiClient
```
The top-level import is preferred for simplicity; the longer path is also valid but less commonly used in examples.
Configuration
```
from docusign_esign import Configuration
```
The top-level import is preferred; the longer path is also valid but less commonly used in examples.
EnvelopesApi
```
from docusign_esign import EnvelopesApi
```
Top-level imports are convenient for frequently used API classes (e.g., EnvelopesApi, AccountsApi).

Quickstart

This quickstart demonstrates how to authenticate with DocuSign using JWT Grant, configure the API client, and make a simple call to retrieve user information. It highlights the critical distinction between authentication server and API server host configurations.

import os
from docusign_esign import ApiClient, Configuration, OAuth, AccountsApi
from docusign_esign.client.api_exception import ApiException

def get_access_token_jwt():
    # Ensure these environment variables are set or replace with actual values
    client_id = os.environ.get('DS_CLIENT_ID', 'YOUR_INTEGRATION_KEY')
    impersonated_user_id = os.environ.get('DS_IMPERSONATED_USER_ID', 'YOUR_IMPERSONATED_USER_ID')
    # Private key should be the raw PEM bytes, often loaded from a file or env var
    private_key_bytes = os.environ.get('DS_PRIVATE_KEY_BYTES', 'YOUR_PRIVATE_KEY').encode('utf-8')
    # Authentication server: 'account-d.docusign.com' for demo, 'account.docusign.com' for production
    auth_server = os.environ.get('DS_AUTH_SERVER', 'account-d.docusign.com')

    if 'YOUR_' in client_id or 'YOUR_' in impersonated_user_id or 'YOUR_' in private_key_bytes.decode('utf-8'):
        print("Please set DS_CLIENT_ID, DS_IMPERSONATED_USER_ID, DS_PRIVATE_KEY_BYTES, and DS_AUTH_SERVER environment variables.")
        return None

    try:
        # Use the JWT helper to request a token
        api_client_oauth = OAuth.ApiClient()
        token_response = api_client_oauth.request_jwt_user_token(
            client_id=client_id,
            impersonated_user_id=impersonated_user_id,
            private_key_bytes=private_key_bytes,
            expires_in=3600, # 1 hour
            scopes=["signature", "impersonation"],
            auth_host="https://" + auth_server
        )
        return token_response.access_token
    except ApiException as e:
        print(f"Error during JWT token request: {e.reason} - {e.body}")
        return None

def main():
    # 1. Get Access Token via JWT Grant
    access_token = get_access_token_jwt()
    if not access_token:
        return

    # DocuSign API server: 'demo.docusign.net' for demo, 'naX.docusign.net' for production (X is a number)
    api_server = os.environ.get('DS_API_SERVER', 'demo.docusign.net')
    if 'YOUR_' in api_server:
        print("Please set DS_API_SERVER environment variable.")
        return

    # 2. Configure API Client
    config = Configuration()
    config.host = f"https://{api_server}/restapi"
    config.access_token = access_token

    api_client = ApiClient(config)

    # 3. Make an API call (e.g., get user info)
    try:
        accounts_api = AccountsApi(api_client)
        user_info = accounts_api.get_user_info()

        print(f"Successfully authenticated user: {user_info.name} ({user_info.email})")
        if user_info.accounts:
            print(f"Default Account ID: {user_info.accounts[0].account_id}")
            print(f"Base URL for API calls: {user_info.accounts[0].base_url}")
        else:
            print("No accounts found for this user.")

    except ApiException as e:
        print(f"Error calling DocuSign API: {e.reason} - {e.body}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == '__main__':
    main()

view raw JSON →