DocuSign API: Search Envelopes by Custom Field Value

To search DocuSign envelopes by a custom field value, call the Envelopes: listStatusChanges endpoint (GET /restapi/v2.1/accounts/{accountId}/envelopes) with the custom_field query parameter formatted as field_name=value, together with the date-range parameters that DocuSign requires on every envelope search. For example, custom_field=Region=West returns envelopes whose envelope custom field named Region holds the value West, and custom_field=Region=%25West%25 (the URL-encoded form of %West%) matches values that merely contain "West". The custom_field parameter is the purpose-built filter for this exact job, and it beats pulling every envelope in a date range and matching values in your own code.

One thing to know before you build on anything else: the older Search Folders endpoint (GET /restapi/v2.1/accounts/{accountId}/search_folders/{searchFolderId}) is marked as deprecated in API v2.1. New integrations should build envelope search on the custom_field, search_text, and date filters available on Envelopes: listStatusChanges. This guide walks through the whole flow: how custom fields get onto envelopes, the request itself, response handling, wildcards, pagination, and the failure modes that trip up most first attempts.

The Short Answer: One GET Request with Two Filters

The minimal working request needs three things: the endpoint, a custom_field filter, and a from_date (DocuSign's envelope search documentation notes that from_date and to_date are required parameters in every envelope search operation). Here is the request as a cURL call:

```bash

curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes" \

-H "Authorization: Bearer {accessToken}" \

-H "Accept: application/json" \

--get \

--data-urlencode "custom_field=Region=West" \

--data-urlencode "from_date=2026-07-01T00:00:00Z" \

--data-urlencode "status=completed"

```

Three details matter in that URL:

1. The value contains an equals sign. custom_field=Region=West must be encoded so the second = survives the query string. Using --data-urlencode (as above) or an encoded string like custom_field=Region%3DWest both work.
2. Dates should be ISO 8601 with an explicit timezone offset. DocuSign recommends explicit offsets such as 2026-07-01T00:00:00Z; without one, the server's time zone is assumed, which quietly shifts your window.
3. status is optional but useful. It accepts a comma-separated list of current statuses such as completed, sent, delivered, declined, or voided, and any matches all statuses.

The response is a JSON object whose envelopes array contains the matching envelope summaries, including envelopeId, status, and emailSubject. If the summary does not carry everything you need, you can follow up on a single envelope with GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/custom_fields, which returns the envelope's custom fields including fieldId, name, and value.

If you are still ramping up on authentication, integration keys, and the demo environment, start with our DocuSign API how-to overview before wiring this into production code.

How Envelope Custom Fields Work Before You Can Search Them

You cannot search what was never stored. In DocuSign, an envelope custom field is metadata attached to the envelope itself, not to a document or a signer. They come in two flavors: text custom fields (free-form values typed by the sender or set via the API) and list custom fields (a value chosen from a predefined list). They are usually defined at the account level by an administrator, then filled in when an envelope is created or sent.

When you create an envelope through the API, you set them in the customFields object:

```json

{

"status": "sent",

"emailSubject": "Master Services Agreement",

"customFields": {

"textCustomFields": [

{

"name": "ClientID",

"value": "CLI-12345",

"show": "true",

"required": "false"

}

]

}

}

```

That ClientID: CLI-12345 pair is what custom_field=ClientID=CLI-12345 will match later. Two practical consequences follow from this design:

• Consistency is your responsibility. The search matches what senders and integrations actually wrote. If one system writes CLI-12345 and another writes cli_12345, only disciplined naming keeps searches reliable. Enforce the pattern in the integration, not in human memory.
• Envelope custom fields are different from tabs (form fields on documents). Values a signer types into a document field are not what custom_field filters. For those, export the envelope's form data and match it on your side; our guide to exporting signed envelope tab and form data as JSON covers that pipeline in detail.

Also note that text custom field values are capped at 100 characters, so treat them as indexing keys (IDs, region codes, matter numbers), not as free-form content storage.

Build the Request Step by Step

Here is the complete flow as a Python function using requests, the way most teams will actually run it:

```python

import requests

def search_envelopes_by_custom_field(access_token, base_url, account_id,

field_name, field_value,

from_date, to_date=None):

url = f"{base_url}/restapi/v2.1/accounts/{account_id}/envelopes"

params = {

"custom_field": f"{field_name}={field_value}",

"from_date": from_date,

}

if to_date:

params["to_date"] = to_date

response = requests.get(

url,

headers={

"Authorization": f"Bearer {access_token}",

"Accept": "application/json",

},

params=params,

)

response.raise_for_status()

return response.json()["envelopes"]

results = search_envelopes_by_custom_field(

access_token=TOKEN,

base_url="https://demo.docusign.net",

account_id=ACCOUNT_ID,

field_name="ClientID",

field_value="CLI-12345",

from_date="2026-01-01T00:00:00Z",

)

for env in results:

print(env["envelopeId"], env["status"], env.get("emailSubject"))

```

Because requests URL-encodes parameters automatically, the embedded = in custom_field=ClientID=CLI-12345 is handled for you. If you build URLs by hand in another language, encode it explicitly (ClientID%3DCLI-12345).

For high match precision, add a client-side verification pass: iterate the returned envelopes and confirm the custom field's exact name and value in the envelope detail before acting on the result. This guards against partial-match surprises when you use wildcards, and against field-name drift across legacy envelopes.

Filter Further: Status, Date Ranges, Folders, and Pagination

A single filter rarely reflects a real business question. Envelopes: listStatusChanges supports combinations that map cleanly onto common scenarios:

Notes on the supporting parameters:

• from_date / to_date bound the date range in which envelope status changed. from_date is required unless you pass envelope_ids or transaction_ids instead.
• status vs. from_to_status: status filters on the envelope's current status; from_to_status qualifies which status change you care about within the window. Requests whose combinations are logically impossible (for example, a delivered qualifier with current status created) return an empty list without a database query, so a confusing empty result is sometimes a logic bug, not missing data.
• Folder scoping: folder_ids and folder_types restrict the search to logical folders such as completed, draft, or recyclebin.
• User scoping: user_id or user_filter narrow results to envelopes where a specific user is sender or recipient.
• Pagination: use count (results per call) with start_position (the zero-based index to start from) to page through large result sets instead of requesting everything at once.
• Trimming payloads: the exclude parameter drops categories like recipients or PowerForm data from the response when you do not need them.

If you are evaluating the total cost of an integration that leans this hard on the API, our explainer on DocuSign API pricing models breaks down how API plans and limits are typically structured.

Exact Match, Wildcard, or Broad Text Search: Choosing the Right Filter

DocuSign gives you three distinct mechanisms, and picking the wrong one is the most common cause of "my search doesn't work":

The wildcard form is the one most people miss: percent signs around the value, URL-encoded as %25 when you build the query string manually. custom_field=ApplicationId=%25DocuSign%25 matches envelopes whose ApplicationId value contains "DocuSign" anywhere in it.

The trade-off is precision. search_text is the bluntest instrument: a search for a client ID will also hit any envelope whose subject, recipient email, or email body happens to contain that string. Reserve search_text for interactive "find me that envelope" features, and use custom_field for automated workflows where an exact key drives downstream logic.

Common Errors and a Pre-Flight Checklist

When a custom field search returns nothing or the wrong things, run through this checklist before suspecting the API:

1. from_date is present and covers the envelope. The envelope may be older than your window, or a missing timezone offset shifted the boundary.
2. The field name matches exactly. Custom field names are case-sensitive strings set at the account level; ClientID and ClientId are different fields.
3. The value is encoded correctly. The inner = needs %3D, and a literal % wildcard needs %25.
4. The status combination is logically possible. Check that current status values can coexist with your date range and any from_to_status qualifier.
5. The field is an envelope custom field, not a document tab. Signer-entered tab values are invisible to custom_field; filter those client-side after exporting form data.
6. The account is right. Multi-account setups often search account A while the envelope lives in account B.
7. The token is valid and unexpired. A 401 on a search call is almost always OAuth expiry rather than a query problem; a 400 points at malformed parameters.

For teams archiving signed agreements out of DocuSign, note that search is only half of a retention strategy. Our walkthrough of the DocuSign Retrieve tool for automating local backups of signed agreements covers the other half.

Scale Tip: Push Beats Poll for High Volumes

Searching is a pull pattern, and pulling on a schedule wastes API budget when most calls return nothing new. For workflows that react to envelope events, such as "when the contract for client X completes, update the CRM," DocuSign Connect webhooks push status updates to your endpoint as they happen. A common hybrid design uses webhooks as the primary trigger and the custom_field search as the reconciliation path: webhooks handle the routine flow, and a nightly search sweep catches anything a missed event left behind. That sweep also doubles as an audit tool, since it re-derives the "what is out for signature per client" view from source data.

If your appetite for envelope data is growing beyond search into full contract intelligence, our look at DocuSign Navigator and AI-powered contract search maps that landscape. And if you are choosing an e-signature platform primarily on the strength of its developer experience, our roundup of the best e-signature REST APIs for developers compares how leading platforms handle exactly these integration jobs.

Build Search-Ready Signing Workflows with Nota Sign

Chasing envelopes by metadata is a symptom of a deeper need: your agreements should be retrievable, structured data from the day they are created. That retrieval-first design conversation is exactly what integration teams bring to Nota Sign, the global e-signature platform from FaDaDa (法大大). The platform supports signing across 100+ countries and regions, and its regional data centers keep APAC signing traffic close to the counterparties it serves.

If your roadmap involves rebuilding an agreement pipeline around searchable, filterable envelope data, tell us about your integration requirements through the Nota Sign contact page. The team will scope the discussion around your volume, your regions, and the systems your envelopes need to feed.