# Filtering and Searching with Common Paper API

This guide will walk you through the process of filtering and searching agreement data using the Common Paper API. We will provide `curl` examples to demonstrate how to interact with the API.

## Filtering Agreements

To filter agreements, you can utilize query parameters with the API endpoints.

### Example: Filtering Agreements by Status

To filter agreements based on their status, you can use the following `curl` command:

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[status_eq\]=signed" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Replace YOUR_API_KEY with your actual API key.

In this example, the filter parameter is `filter[status_eq]=signed`, which filters agreements with a "signed" status. The `_eq` is the operator that stands for equals. There are a number of supported operators such as `_gt` (greater than), `_not_eq` (not equal), and `_cont` (contains). The full list can be found [here](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/).

## Searching Agreements

To search for agreements containing specific keywords or matching specific conditions, use the ransack gem's search predicates in the query parameters.

### Example: Searching Agreements with fuzzy matching

To search for agreements containing "gmail.com" in the recipient_email, use the following curl command:

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[recipient_email_cont\]=gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

In this example, the filter parameter is `filter[purpose_cont]=business`, which searches for agreements with a purpose containing the word "business".

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[purpose_cont\]=business" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example: Searching Agreements by Date

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[sent_date_gt\]=2023-03-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To search for agreements sent after a specific date, use the `_gt` operator like in the following curl command:

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[sent_date_gt\]=2023-03-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example: Searching Agreements by Multiple Conditions

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[status_eq\]=signed&filter\[recipient_email_cont\]=gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To search for agreements with a "signed" status and a gmail.com domain, use the following curl command:

```bash
curl -X GET "https://api.commonpaper.com/v1/agreements?filter\[status_eq\]=signed&filter\[recipient_email_cont\]=gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

In this example, we combine two filter parameters: `filter[status_eq]=signed` and `filter[recipient_email_cont]=gmail.com`.

For more advanced queries and filtering options, refer to the [Ransack documentation](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/).