> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Configure agreement queries

> Learn how to configure queries to get agreements and your options for filtering the results.

When you get agreements using the [Agreements:getAgreementsList](/docs/agreement-manager-api/reference/agreementmanager/agreements/getagreementslist)  endpoint, you can apply [Open Data Protocol](https://www.odata.org/getting-started/basic-tutorial/) (OData) query model parameters to select and filter the results to return exactly the agreements you need. This query model currently supports basic filtering, as well as the following four query parameters:

* [`$filter`](/docs/agreement-manager-api/concepts/configure-agreement-queries#filter-on-agreement-fields-using-filter)
* [`$select`](/docs/agreement-manager-api/concepts/configure-agreement-queries#return-only-the-result-fields-that-you-need-by-using-select)
* [`$search`](/docs/agreement-manager-api/concepts/configure-agreement-queries#use-search-for-keyword-and-partial-information-searches)

## Filter queries with basic syntax

The following bracketed operators are supported in basic queries that do not include any query parameters:

* `[gt]`: Greater than
* `[gte]` / `[ge]`: Greater than or equal to
* `[lt]`: Less than
* `[lte]` / `[le]`: Less than or equal to
* `[ne]` or `[eq]`: Not equal to or equal to

Basic queries support the following data types and operators:

| **Data Type**                                                                     | **Type Supported Operators** |
| --------------------------------------------------------------------------------- | ---------------------------- |
| `string`                                                                          | `=`                          |
| `number (integer, float, etc.)`                                                   | `=, gte, gt, lte, le`        |
| `datetime`                                                                        | `=, gte, gt, lte, le`        |
| `duration (`[ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html)`)` | `=, gte, gt, lte, le`        |

You can combine multiple filter conditions by including them as separate query parameters and linking them with ampersand (`&`) .

Example query for multiple basic filter conditions:

`GET /agreements?status=COMPLETE&effective_date[gte]=2025-01-01`

Properties of complex types can be accessed using a forward slash notation (`/`). This is the same syntax as accessing resources in the URI.

Example complex type property:

`companies(1)/address/street`

**Note**: Filter parameters and operations are case insensitive.

### List of filterable fields for each support resource type

#### Agreement

| **Supported Key**                                                                             | **Type**                                                                      |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `id, OR id[in]`                                                                               | `UUID`                                                                        |
| `status`                                                                                      | `string`                                                                      |
| `Parties.name_in_agreement`                                                                   | `string`                                                                      |
| `metadata.created_at` AND `created_at`                                                        | `datetime` [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) |
| `source_name`                                                                                 | `string`                                                                      |
| `source_id`                                                                                   | `string`                                                                      |
| `file_name`                                                                                   | `string`                                                                      |
| `title`                                                                                       | `string`                                                                      |
| `related_agreement_documents.parent_agreement_document_id` AND `parent_agreement_document_id` | `UUID`                                                                        |
| `languages`                                                                                   | `string[]` [BCP-47](https://www.rfc-editor.org/info/bcp47)                    |
| `provisions.effective_date` AND `effective_date`                                              | `datetime` `ISO-8601`                                                         |
| `provisions.expiration_date` AND `expiration_date`                                            | `datetime` `ISO-8601`                                                         |
| `provisions.execution_date` AND `execution_date`                                              | `datetime` `ISO-8601`                                                         |
| `provisions.term_length` AND `term_length`                                                    | `duration` `ISO-8601`                                                         |

#### Workflow

| **Supported Key**                      | **Type**              |
| -------------------------------------- | --------------------- |
| i`d`                                   | `UUID`                |
| `name`                                 | `string`              |
| `account_id`                           | `string`              |
| `status`                               | `string`              |
| `metadata.created_at` AND `created_at` | `datetime` `ISO-8601` |
| `metadata.updated_at` AND `updated_at` | `datetime` `ISO-8601` |
| `metadata.created_by` AND `created_by` | `UUID`                |

#### Workflow instance

| **Supported Key**                                          | **Type**              |
| ---------------------------------------------------------- | --------------------- |
| `id`                                                       | `UUID`                |
| `name`                                                     | `string`              |
| `workflow_status`                                          | `string`              |
| `template_id`                                              | `UUID`                |
| `account_id`                                               | `UUID`                |
| `started_at`                                               | `datetime`            |
| `started_by`                                               | `UUID`                |
| `started_by_name`                                          | `string`              |
| `started_by_role`                                          | `string`              |
| `expires_at`                                               | `datetime`            |
| `total_steps`                                              | `integer`             |
| `last_completed_step`                                      | `integer`             |
| `tags`                                                     | `string`              |
| `metadata.workflow_version` AND `workflow_version`         | `datetime` `ISO-8601` |
| `metadata.workflow_metadata_id` AND `workflow_metadata_id` | `datetime` `ISO-8601` |
| `metadata.workflow_created_by` AND `workflow_created_by`   | `UUID`                |

## Filter on agreement fields using `$filter`

The `$filter` query parameter enables you to perform more complex query filtering than basic syntax. You can use `$filter` to combine multiple conditions with and, or, in, contains, and group clauses with parentheses. Nested properties use `/` path syntax, such as `provisions/effective_date`.

Use cases include:

* AI agents with structured filters, which can translate user constraints into an OData `$filter` instead of pulling everything and filtering client-side.
* Renewal dashboards and reviews, such as filters for all active agreements expiring within a certain period of time. Common filters on fields such as `status`, `review_status`, `review_completed_at`, `metadata/created_at`, `provisions/effective_date`, `provisions/expiration_date`, or `provisions/execution_date`.
* Party-specific views for an agreement, such as showing all agreements where the specified party is a signer using a field like `parties/name_in_agreement`.

Example query syntax:

`GET /employees?$filter=role eq 'Manager' or (role eq 'Developer' and department eq 'Engineering')`

## Return only the result fields that you need by using `$select`

The `$select` parameter enables you return only the values of exact fields that you care about for the objects in a result set.

To use `$select`, you specify the relevant field names as values for the query parameter before executing your GET agreements API call. Using path syntax, you can project fields at any depth.

Example query:

`GET /agreements?$select=title,parties/name,provisions/term_length`

Implementing `$select` can help you reduce costs for interacting with agreements using Large Language Models (LLMs). Unnecessary data in API responses can increase the cost of running LLMs against your data. By using `$select` to only return the specific fields that you need, you can reduce payload size by 70-90% and keep your costs low by minimizing the data that the LLM processes.

For example, an LLM answering a question about the names of parties in an agreement does not need data about the agreement’s value or renewal date, allowing you to query specifically for name fields and not process any unnecessary data.

## Use `$search` for keyword and partial-information searches

The `$search` query parameter enables you to perform searches using partial information, such as a probable keyword or a company name mentioned somewhere in an agreement document, rather than requiring exact terms or complicated queries.

`$search` is especially useful for [AI Agents](/platform/mcp-server). It can be difficult to construct precise `$filter` queries based on natural language questions, sometimes leading to reduced accuracy or additional cost. `$search` more fully supports natural language queries and it is more flexible and simpler to use than `$filter`, but may only access data from designated supported searchable fields.

`$search` can also be used as a broad keyword search to generate a result set, which you then filter using `$filter` and `$select` in later API calls.

The following example query returns agreements where searchable content matches the “market research” term, enabling natural discovery without requiring field-specific knowledge. In this case, every document with a field containing the term “market research” will be returned. `$search` queries are case-insensitive.

`GET /agreements?$search="market research"`

## Next steps

* See the [Agreements:getAgreementsList](/docs/agreement-manager-api/reference/agreementmanager/agreements/getagreementslist) reference documentation.
* See the Agreement Manager [How-to guides](/docs/agreement-manager-api/how-to).
* Learn about [Agreement Manager API use cases](/docs/agreement-manager-api/concepts/use-cases).