Copy page

Documentation

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:

Code
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.

Every filter needs a field and an operator inside the brackets. A bare value such as filter=signed returns a 400 error describing the expected format.

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:

Code
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".

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

Example: Searching Agreements by Date

Code
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:

Code
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

Code
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:

Code
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.