Configure agreement queries

When you get agreements using the Agreements:getAgreementsList endpoint, you can apply Open Data Protocol (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
• $select
• $search

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:

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

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. 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 reference documentation.
• See the Agreement Manager How-to guides.
• Learn about Agreement Manager API use cases.