DocuSign API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the DocuSign eSignature API enables applications to programmatically send, sign, and manage documents. The key steps to get started involve creating a developer account, configuring API credentials, and executing a foundational API call, typically to send an envelope for signing. DocuSign provides a robust eSignature REST API documentation suite and SDKs for multiple programming languages including C#, Java, Node.js, PHP, Python, and Ruby.

A typical getting started workflow for DocuSign API involves:

1. Account Creation: Register for a developer account to access the sandbox environment.
2. App Configuration: Create an API integration key and configure redirect URIs.
3. Authentication Setup: Implement an OAuth 2.0 flow to obtain an access token.
4. First API Call: Construct and send a basic request, such as creating and sending an envelope.

DocuSign offers a wide range of code examples to assist with various API functions, from basic envelope creation to more advanced features like embedded signing and template usage.

Create an account and get keys

To begin, you need a DocuSign developer account. This provides access to a sandbox environment where you can test API calls without affecting production data or incurring charges.

Step 1: Sign up for a developer account

Navigate to the DocuSign Developer Center and sign up for a free developer account. This typically includes a 30-day free trial for personal and business-level features, allowing full exploration of the platform's capabilities before committing to a paid plan.

Step 2: Create an API integration key

Once logged into your developer account, you’ll need to create an API Integration Key. This key serves as your application's identifier when making API requests.

1. From the DocuSign eSignature Admin console, go to Apps and Keys.
2. Select Add App & Integration Key.
3. Provide a descriptive name for your application and click Add.
4. Note down the generated Integration Key (Client ID). This is a crucial credential.

Step 3: Configure authentication and redirect URIs

DocuSign API primarily uses OAuth 2.0 for authentication. For most server-side applications, the Authorization Code Grant flow is recommended, while client-side applications might use the Implicit Grant or JWT Grant. You'll need to specify one or more Redirect URIs for your application.

1. On the same Apps and Keys page, locate your newly created integration key.
2. Under OAuth 2.0 Configuration, click Add URI next to Redirect URIs.
3. Enter the URI where DocuSign should redirect the user after successful authentication (e.g., http://localhost:8080/auth for local development).
4. For production applications, ensure these URIs are HTTPS.
5. Generate a Secret Key if your application requires it (e.g., for Authorization Code Grant). Keep this secret secure and do not expose it in client-side code.

For more details on OAuth 2.0, consult the OAuth 2.0 specification.

Your first request

After setting up your account and obtaining credentials, the next step is to make a successful API call. A common first request is to send a simple envelope for signing. This typically involves obtaining an OAuth access token, constructing a request body, and sending it to the DocuSign API endpoint.

Step 1: Obtain an access token

The method for obtaining an access token depends on the OAuth 2.0 grant type you implement. For testing, using the Authorization Code Grant can be done manually or via an SDK helper function.

Example (using Authorization Code Grant flow concept):

1. Construct an authorization URL, including your integration key, redirect URI, and desired scopes (e.g., signature, impersonation).
2. Direct a browser to this URL. The user will log into DocuSign and grant consent.
3. DocuSign redirects the browser back to your specified Redirect URI, appending an authorization code.
4. Your application exchanges this authorization code for an access token and a refresh token by making a POST request to DocuSign's token endpoint, including your integration key and secret key (if applicable).

DocuSign provides detailed authentication guides for various grant types.

Step 2: Construct and send an envelope

Once you have an access token, you can make API calls. The following example demonstrates a basic request using curl to create and send an envelope, which is the primary container for documents and signature requests in DocuSign.

curl --request POST \
  --url 'https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{  
    "emailSubject": "Please sign this document",
    "documents": [
        {  
            "documentBase64": "JVBERi0xLjQKJfsdjfsd...replace with base64 encoded PDF...",
            "documentId": "1",
            "fileExtension": "pdf",
            "name": "Example Document"
        }
    ],
    "recipients": {  
        "signers": [
            {  
                "email": "[email protected]",
                "name": "John Doe",
                "recipientId": "1",
                "routingOrder": "1"
            }
        ]
    },
    "status": "sent"
}'

Replace placeholders:

• {accountId}: Your DocuSign account ID, available in the eSignature Admin console under API and Keys.
• YOUR_ACCESS_TOKEN: The OAuth 2.0 access token you obtained.
• JVBERi0xLjQKJfsdjfsd...: A Base64-encoded PDF document. You can use online tools or programmatic methods to encode your PDF.
• [email protected] and John Doe: The email and name of the recipient.

Ensure the status field is set to sent to immediately send the envelope for signing. If you set it to created, the envelope will be saved as a draft.

Quick Reference: Getting Started Steps

Common next steps

After successfully sending your first envelope, consider these common next steps to further integrate DocuSign into your application:

• SDKs: Utilize one of the official DocuSign SDKs (C#, Java, Node.js, PHP, Python, Ruby) to simplify API interactions and reduce boilerplate code. SDKs handle authentication, request signing, and response parsing.
• Embedded Signing: Implement embedded signing workflows where signers complete documents directly within your application's user interface, rather than via email. This requires generating a recipient view URL using the API.
• Templates: Leverage DocuSign templates for frequently used documents. Templates pre-define document structure, recipient roles, and signature fields, streamlining the envelope creation process.
• Webhooks (Connect): Set up DocuSign Connect webhooks to receive real-time notifications about envelope status changes (e.g., signed, declined, voided). This is crucial for building responsive applications that react to signing events.
• Error Handling: Implement robust error handling based on the DocuSign API error codes and best practices to manage failed requests and provide meaningful feedback to users.
• Go-Live Process: Understand and follow the DocuSign Go-Live Checklist to move your application from the sandbox to the production environment. This typically involves a review process by DocuSign.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Base URL: Ensure you are using the correct base URL for the sandbox environment: https://demo.docusign.net/restapi/v2.1. Do not use the production URL (https://na2.docusign.net/restapi/v2.1 or similar) for sandbox testing.
• Verify Access Token: Confirm your access token is valid and not expired. OAuth 2.0 access tokens have a limited lifespan. If expired, refresh it using your refresh token or re-authenticate.
• Incorrect Account ID: Double-check that the accountId in your request URL matches the one from your developer account (available in the eSignature Admin console under API and Keys).
• Bad Request Body: Review your JSON request body for syntax errors, missing required fields, or incorrect data types. Even a misplaced comma can cause a 400 Bad Request error.
• Insufficient Scopes: Ensure your access token was granted with the necessary OAuth scopes. For sending envelopes, the signature scope is typically required.
• Base64 Encoding: Confirm your PDF document is correctly Base64 encoded. Invalid encoding will lead to document processing errors.
• Network Issues/Firewall: Verify that your development environment can reach the DocuSign API endpoints. Firewall rules or proxy settings might block requests.
• DocuSign API Status: Check the DocuSign System Status page for any ongoing outages or service disruptions.
• Consult DocuSign Logs: In your DocuSign developer account, you can often find API call logs that provide more specific error messages, which can be invaluable for debugging.