Some API endpoints return lists of objects and filters are crucial in precisely targeting the data you want to receive. Instead of receiving a large volume of data, you can specify criteria to obtain responses tailored to your needs.

How do filters work?

Filters are added as parameters at the end of the endpoint URL, after adding a ? when calling an endpoint.

They consist of three elements:

A property to filter by specifying the attribute to search on (for example a creation date or a status).
An operator: to determine the type of comparison to perform (for example equal, between, in).
A value: to specify the condition to be met to return results.

Here is how the endpoint URL should look like when using filters: URL?property[operator]=value.

Filters can be combined using the & symbol to apply multiple criteria simultaneously. In this situation, the endpoint URL should look like that: URL?property_1[operator]=value_1&property_2[operator]=value_2.

When multiple filters are combined, all criteria must be met for a result to be included in the response. This allows for more precise and targeted queries.

Operators available

Here are all the operators available when filtering data. Please note that not all operators are available for all fields.

Single value operators

Those operators only accept one value.

Operator	Description	Example
`eq`	Searches for a value that exactly matches the specified criteria.	`created_at[eq]=2025-01-10`
`before`	Searches for values that are earlier than the specified value. Commonly used with dates.	`created_at[before]=2025-01-10`
`after`	Searches for values that are later than the specified value. Commonly used with dates.	`created_at[after]=2025-01-10`

Range operators

Operator	Description	Example
`between`	Searches for values within a specified range. This operator is primarily used for date ranges. Both values in the range are inclusive. Accept two comma-separated values. The first value must be smaller than the second value.	`created_at[between]=2025-01-10,2025-01-15`

Multiple values operators

Operator	Description	Example
`in`	Searches for values that match any of the specified options. This is useful for properties that can take multiple discrete values. Accept one or more comma-separated values.	`status[in]=draft,pending,completed`

Filters available

To know which filters are available for a specific listing endpoint, please refer to the Query Param section of the API Reference pages. As an example, you will find here filters available for Signature Requests listing.

Exemple: use filters on `GET /signature_requests`

The GET /signature_requests endpoint allows you to list Signature Requests. This request can return many items depending on the number of Signature Requests on your account. With filters, you can refine your search based on your needs, to receive only the data that matter.

Here are some examples:

Example 1: Search for Signature Requests created between two dates

GET /signature_requests?created_at[between]=2025-01-10,2025-01-15

Returns all Signature Requests created between January 10, 2025, and January 15, 2025.

Example 2: Search for Signature Requests originating from the API with a "draft" status

GET /signature_requests?source[eq]=public_api&status[eq]=draft

Returns all Signature Requests created with the API with a "draft" status.

Example 3: Search for Signature Requests by multiple statuses

GET /signature_requests?status[in]=completed,canceled

Returns all requests with a status of "completed" or "canceled."