Enable Navigator API Full-Text Search ($search) on Demo Account

​@HariGopal Patel  Can you please try again with adding one more scope to your token “search_read”.
we will update our documentation soon

​@venkat-kotu Thank you for the quick response.

Adding the search_read scope resolved the issue, and the $search parameter is now working correctly in the Navigator API.

Thanks again!

Documentation was updated to show this scope is needed https://developers.docusign.com/docs/agreement-manager-api/auth/
Thanks for reporting this issue!

Hi ​@venkat-kotu , ​@Inbar.Gazit and other DocuSign Community,

We have some additional questions regarding the Navigator Agreements List API implementation.

We are currently using the following endpoint:

GET /v1/accounts/{accountId}/agreements

Environment:
https://api-d.docusign.com

During implementation, we encountered several limitations/questions related to filtering and searching behavior. We would appreciate clarification on the supported capabilities and recommended implementation approach.

1. Agreement Status Filters

In the DocuSign UI, we can see agreement statuses such as:

• Active

• Inactive

• Effective Soon

• Expiring Soon

• Renewing Soon

However, these status values are not returned in the Agreements List API response, and we could not find any supported $filter fields for them.

Questions:

• How can we retrieve these status values through the API?

• Is there any supported way to filter agreements using these statuses?

2. Party Filters / Multi-Party Filtering

In the DocuSign UI, we can see a Parties filter that supports selecting multiple parties simultaneously with party role while filtering agreements.

However, while reviewing the documentation:

• The GetAllParties endpoint exists under the CLM API:
  /v2/{accountId}/parties

• The documentation mentions CLM APIs are available only for CLM customers with production accounts

• The Agreements List API documentation does not clearly mention support for filtering by multiple parties

Questions:

• Is a CLM-enabled account required to retrieve Parties data for Navigator filtering?

• How can we enable/access the Parties API in demo or development environments?

• Does the Agreements List API officially support filtering by multiple parties?

• If supported, what is the correct syntax for passing multiple parties in filters?

• If not supported, what is the recommended way to replicate the same filtering behavior available in the DocuSign UI?

3. Combining Search and Filters

When we try to combine $search and $filter in the same request:

Example:
/agreements?$search=ABC Corp.&$filter=provisions/expiration_date le 2026-05-31 and provisions/effective_date le 2026-06-02 and provisions/execution_date le 2026-06-01

We receive:
{
"title": "Bad Request",
"detail": "The $search and $filter query parameters cannot be combined in the same request."
}

Similarly, when combining basic query parameters with $filter:

Example:
/agreements?review_status=COMPLETE&$filter=provisions/expiration_date le 2026-05-31

We receive:
{
"title": "Bad Request",
"detail": "Basic query parameters and OData $filter cannot be mixed."
}

Additionally, when using basic query parameters together with $search, the results returned are not matching the expected filtered output.

At the moment, it appears there are several restrictions around:

• $search

• $filter

• basic query parameters

• party filters

• computed status filters

Because of these limitations, we are unsure how to fully replicate above filtering/search experience currently available in the DocuSign UI.

Could you please clarify:

• Which combinations are officially supported?

• Whether these are current API limitations by design

• Recommended implementation/workaround approaches to achieve advanced filtering similar to the DocuSign UI

#3 
Yes they are mutually exclusive and cannot be applied the same time. Thanks for bringing this to our attention (Ideally  this should 400 when basic query parameters together with $search) we will fix this.
#2 

The GetAllParties endpoint is completely diff product and is not under agreement manager api at the moment.
and parties filtering  also have some limitations 

you can try basic filtering /agreements?parties.name_in_agreement=John
#1
We don’t support the UI filters as of today, you need to set explicit filter if you want to filter by expiration_date etc. 

Hi ​@venkat-kotu , ​@Inbar.Gazit , and other DocuSign Community members,

We have another question regarding pagination when using the Navigator Agreements API search functionality.

Endpoint:
GET /v1/accounts/{accountId}/agreements

Environment:
https://api-d.docusign.com

Scenario 1: Pagination without Search

When we retrieve agreements without using $search, pagination works as expected.

Example:

/agreements?limit=10&ctoken=WyIyMDI2LTA1LTIxVDEwOjE0OjI3Ljk4OTUxOVoiLCI1NTk2YjlhNmZmNWU0Nzc0YTdmYWJlOTczZGMyNzg2MyJd

This successfully returns the next page of results.

Scenario 2: Pagination with Search

When we perform a search and then use the continuation token returned from that search request, we receive a validation error.

Example:

/agreements?limit=10&ctoken=MTB8ZTJjYmMxOTctMzVjZC00MTdiLWEyN2MtMWMwOGVmZTdiNWY1&$search=png

Response:

{
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input format. Please check the request parameters.",
  "errors": [
    {
      "code": "invalid_format",
      "message": "The value provided could not be parsed to the expected type."
    }
  ]
}

Questions:

1. Is pagination supported for search results?

2. Is Another limitation of the API?

Any guidance would be greatly appreciated. Thank you for your help.

​@HariGopal Patel 
we fixed one issue and this should be working now 
/agreements?$filter=parties/name_in_agreement eq 'name'

will get back on the “Scenario 2: Pagination with Search”

​@HariGopal Patel 
the $search with pagination token should be working now. we fixed the issue. Thank you!

Hii ​@venkat-kotu ,

For a SaaS application that allows multiple customer DocuSign accounts to connect via OAuth Authorization Code Grant and use Navigator APIs, what additional Go-Live, licensing, entitlement, or review requirements apply?

Hi ​@venkat-kotu  and DocuSign Community,

While validating the Navigator Agreements List API against the DocuSign UI, we noticed some inconsistencies in the Agreement Type values returned by the API compared to what is displayed in the UI.

Issue 1: Formatting Difference

For the same agreement, the API returns:

{
  "file_name": "DWSample1-RTF.rtf",
  "type": "OfferLetter"
}

However, the DocuSign UI displays:
 

Offer Letter

The API value does not contain spaces between words, while the UI displays a user-friendly formatted value with spaces.

We have observed this behavior for multiple agreement types where the displayed value contains multiple words.

Issue 2: Agreement Type Mapping Difference

For another agreement, the DocuSign UI displays:
 

Miscellaneous

However, the API returns:
 

{
  "type": "Other"
}

This appears to be a different value rather than just a formatting difference.

Issue 3: Agreement Type Appears Incomplete in API Response

We found another example where the Agreement Type displayed in the UI does not seem to match the value returned by the API.

The API returns:

{
  "id": "f2d68c3c-858d-4acf-98fd-255624353382",
  "title": "California Avocado, Cheese & Charcuterie Board Featuring California Avocado Goat Cheese Dip With Crispy Prosciutto",
  "file_name": "File1.PDF",
  "document_id": "09b1ca5e-7a03-4c0a-b715-7360b766b2e7",
  "type": "InvestmentAccount"
}

However, the DocuSign UI displays:
 

Investment Account Agreement

In this case, the difference appears to be more than simple formatting:

• API value: InvestmentAccount

• UI value: Investment Account Agreement

Issue 4: Abbreviated Agreement Type Value Returned by API

We found another example where the Agreement Type returned by the API differs significantly from the value displayed in the DocuSign UI.

The API returns:

{
  "id": "becab6bc-695b-4bbe-a002-e2f1119238be",
  "title": "California Avocado, Cheese & Charcuterie Board Featuring California Avocado Goat Cheese Dip With Crispy Prosciutto",
  "file_name": "File1.pdf",
  "document_id": "548cb4b0-5b26-4a5d-b25e-9fe94deed47e",
  "type": "Nda",
  "category": "BusinessServices",
  "status": "COMPLETE"
}

However, the DocuSign UI displays:
 

Non-Disclosure Agreement

In this case:

• API value: Nda

• UI value: Non-Disclosure Agreement

Across several examples, we have observed differences such as:

Our goal is to display agreement types in our application exactly as they appear in the DocuSign UI, and we would appreciate guidance on the recommended approach.

Thank you.

Hii ​@venkat-kotu
 

Does the type field returned by the Agreements List API represent an internal agreement type key/enum rather than the display value shown in the DocuSign UI?

If so, is there an API, metadata endpoint, or official mapping table available that can be used to convert these values to the same display labels used in the UI?