DocuSign API: How to search for envelopes by a custom field value?

Navigating DocuSign’s API for Efficient Envelope Management

In the competitive landscape of digital signature solutions, DocuSign’s API stands out as a robust tool for developers and businesses aiming to automate workflows. One common challenge is retrieving specific envelopes—DocuSign’s term for document packages—based on custom metadata. This capability is crucial for enterprises handling high volumes of agreements, enabling targeted searches without manual sifting. From a business perspective, mastering such API features can streamline compliance audits, sales tracking, and customer support, ultimately reducing operational costs.

Comparing eSignature platforms with DocuSign or Adobe Sign?

eSignGlobal delivers a more flexible and cost-effective eSignature solution with global compliance, transparent pricing, and faster onboarding.

👉 Start Free Trial

Understanding Envelopes and Custom Fields in DocuSign API

DocuSign envelopes represent the core unit of electronic signing, encapsulating documents, recipients, and signing fields. Custom fields, also known as text or tab fields, allow users to embed metadata like contract IDs, client names, or status tags directly into the envelope. These fields are not just for display; they enable programmatic querying, which is invaluable for integrations in CRM systems or custom dashboards.

From a commercial standpoint, leveraging custom fields for searches enhances data governance. Businesses in regulated industries, such as finance or healthcare, can use them to filter envelopes by compliance markers, ensuring quick access during audits. DocuSign’s API, part of its Developer Platform, supports this through RESTful endpoints, with pricing tiers like the Intermediate plan ($3,600/year) offering up to 100 envelopes per month for such operations.

Step-by-Step Guide: Searching Envelopes by Custom Field Value

To search for envelopes using a custom field value via the DocuSign API, you’ll need an active developer account and API credentials. This process assumes you’re using the eSignature REST API v2.1, which is the current standard as of 2025. Here’s a neutral, practical walkthrough based on official documentation.

Prerequisites and Setup

1. Obtain API Access: Sign up for a DocuSign developer sandbox at developer.docusign.com. Generate an integration key (client ID) and secret for OAuth authentication. For production, upgrade to a paid plan—Starter at $600/year suits basic searches.

2. Define Custom Fields: When creating an envelope, add custom fields via the API. Use the customFields object in the envelope definition. For example:

   {
     "status": "sent",
     "emailSubject": "Agreement for Review",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   This embeds “CLI-12345” as a searchable value under the “ClientID” field.

3. Authentication: Use JWT or Auth Code Grant flow. A sample JWT request in Python (using the requests library) looks like:

   import requests
   import jwt
   import time
   
   def get_jwt_token(integration_key, user_id, rsa_key, account_id):
       claim = {
           "iss": integration_key,
           "sub": user_id,
           "aud": "account-docusigncom",
           "iat": int(time.time()),
           "exp": int(time.time()) + 3600,
           "scope": "signature impersonation"
       }
       token = jwt.encode(claim, rsa_key, algorithm='RS256')
       response = requests.post(
           "https://account-docusign.com/oauth/token",
           headers={"Authorization": f"Bearer {token}"},
           data={
               "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
               "assertion": token
           }
       )
       return response.json()["access_token"]
   

   Replace placeholders with your credentials. This token authenticates subsequent API calls.

Performing the Search

The key endpoint is GET /accounts/{accountId}/envelopes/search, but for custom field filtering, combine it with query parameters or use the more flexible GET /envelopes with search criteria. DocuSign’s search API allows querying by custom fields via the searchText parameter, which matches against envelope metadata including custom values.

• Basic Search Endpoint: Use GET /accounts/{accountId}/envelopes?search_text={value}. This scans envelope subjects, names, and custom fields.

  For precise custom field matching, leverage the query parameter in advanced searches. However, direct custom field querying requires the Envelopes: listStatusChanges or similar permissions.

  Sample cURL request:

  curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes?search_text=CLI-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
  

  Response snippet:

  {
    "envelopes": [
      {
        "envelopeId": "abc-123-def",
        "status": "completed",
        "customFields": {
          "textCustomFields": [
            {
              "name": "ClientID",
              "value": "CLI-12345"
            }
          ]
        }
      }
    ]
  }
  

• Advanced Filtering with Custom Fields: For envelope-specific searches, first retrieve envelopes in a date range or status, then filter client-side. DocuSign recommends using the fromDate and toDate parameters alongside search_text for efficiency. If your volume exceeds quotas (e.g., 100 envelopes/month in Intermediate plan), consider upgrading to Advanced ($5,760/year) for bulk capabilities.

  In code, parse the response to match exact custom field values:

  import json
  
  response = requests.get(
      f"https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json"
      },
      params={"search_text": "CLI-12345", "from_date": "2025-01-01T00:00:00Z"}
  )
  envelopes = response.json()["envelopeSummary"]["envelopes"]
  matching_envelopes = [
      env for env in envelopes
      if any(cf["name"] == "ClientID" and cf["value"] == "CLI-12345" for cf in env.get("customFields", {}).get("textCustomFields", []))
  ]
  print(json.dumps(matching_envelopes, indent=2))
  

Best Practices and Limitations

• Quotas and Costs: Searches count toward envelope API limits. Exceeding them incurs overage fees or requires Enterprise customization.
• Security: Always use HTTPS and role-based access to prevent unauthorized queries.
• Error Handling: Common issues include 401 (invalid token) or 400 (bad query). Log responses for debugging.
• Scalability: For high-volume searches, integrate with DocuSign’s Connect webhooks to push updates, reducing polling needs.

This API functionality positions DocuSign as a leader for automated compliance, though businesses should evaluate total costs, including add-ons like Identity Verification.

DocuSign: A Market Leader in eSignature Solutions

DocuSign, a pioneer in electronic signatures since 2004, offers comprehensive tools for document management. Its eSignature platform includes plans from Personal ($120/year) to Business Pro ($480/user/year), with API access via separate Developer plans. Key features encompass templates, bulk sends, and integrations with over 400 apps. For advanced needs, DocuSign’s Intelligent Agreement Management (IAM) combines CLM (Contract Lifecycle Management) with AI-driven insights, automating redlining and risk assessment. IAM is ideal for enterprises, though pricing is custom and can escalate with seats and envelopes.

Adobe Sign: Robust Integration for Enterprise Workflows

Adobe Sign, part of Adobe Document Cloud, excels in seamless integration with PDF tools and creative suites. Pricing starts at around $10/user/month for individuals, scaling to enterprise custom plans. It supports custom fields and API searches similar to DocuSign, with endpoints like /agreements for querying metadata. Strengths include strong Adobe ecosystem ties and global compliance, but it may require additional licensing for advanced API features. Businesses value its focus on document authoring alongside signing.

eSignGlobal: Tailored for APAC and Global Compliance

eSignGlobal emerges as a specialized player, particularly in the Asia-Pacific (APAC) region, where electronic signature regulations are fragmented, high-standard, and strictly regulated. Unlike the framework-based ESIGN/UETA in the US or eIDAS in Europe—which rely on email verification or self-declaration—APAC demands ecosystem-integrated standards. This involves deep hardware/API-level docking with government-to-business (G2B) digital identities, raising technical barriers significantly higher than Western models. eSignGlobal addresses this with compliance across 100 mainstream global countries and regions, holding advantages in APAC through local data centers in Hong Kong and Singapore. It supports seamless integrations like Hong Kong’s iAM Smart and Singapore’s Singpass for robust identity verification. Priced competitively, the Essential plan costs $299/year (about $16.6/month equivalent when annualized), allowing up to 100 documents for signature, unlimited user seats, and access code verification—all on a compliant, cost-effective basis that undercuts many rivals while maintaining legal efficacy.

Looking for a smarter alternative to DocuSign?

eSignGlobal delivers a more flexible and cost-effective eSignature solution with global compliance, transparent pricing, and faster onboarding.

👉 Start Free Trial

HelloSign (Dropbox Sign): Simplicity for SMBs

HelloSign, now Dropbox Sign, prioritizes user-friendly interfaces for small to medium businesses. Free for up to three documents monthly, paid plans start at $15/month. Its API supports envelope searches via custom fields using endpoints like /templates and /signatures, though it’s less granular than DocuSign’s. Ideal for quick integrations with Dropbox, it focuses on ease over enterprise-scale customization.

Comparative Overview of eSignature Platforms

This table highlights neutral trade-offs; selection depends on regional needs and scale.

In summary, while DocuSign’s API empowers precise envelope searches, exploring alternatives can optimize for specific markets. For regional compliance, eSignGlobal offers a balanced option as a DocuSign substitute.