Searching and queries

Using url queries to search and list contracts

When listing contracts, you most likely don't want all the information of every single contract at the same time. You can narrow down your results with various url parameters and the API will return only the contracts you were looking for.

Structure of a request url

Here is an example url for a simple search for contracts that have important in their title, documents or textual metadata fields:
https://sandbox.zefort.com/api/contracts/?q=important

Let's add a condition to our search. A GET-request with following url returns a list of contracts, that have important somewhere in their text content and are attached to tag tagged:
https://sandbox.zefort.com/api/contracts/?q=important&tags=tagged

A contract object has lots and lots of attributes and sometimes you only need the id and the title. By adding minimal=True parameter, the results in our response is reduced quite a bit: https://sandbox.zefort.com/api/contracts/?q=important&tags=tagged&minimal=True

Note that these url's don't do anything by themselves, but need to be used in addition to a request with authorization.

Second note: In most cases you will be able to slip the parameters as a dictionary or a json in your request method, which will parse the url for you.

Queries and filters

Search parameters with q -prefix are string queries that match a wider bunch of contracts and rate them by likeness.

All the other parameters are filters that only match contracts that exactly meet their conditions.

Order of the results

• The list of results is sorted by their receive_time by default.
• when queries are used, they'll be sorted by score.
• Using the sort parameter overrides both of the previous rules.

Pagination

See Handling responses with pages

List of possible parameters

The complete list of query parameters for listing contracts can be found in Zefort API Reference.

More examples:

1. Search contracts by title
2. Search contracts by date
3. Sorting results
4. Use case: Titles and ids of not reviewed contracts uploaded after a certain date

1. String search

List all the contracts that have "Important contract" in document contents or textual metadata fields:

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'

response = requests.get(
    'https://sandbox.zefort.com/api/contracts/', 
    auth=(ZEFORT_APIKEY, ''),
    params={
        'q': 'important contract',
    })

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/?q=important contract" \
     -u $ZEFORT_APIKEY:

2. Search contracts by date

In the following example, we list all the contracts created between
the 25th and 28th of April in 2022 (includes 25th, excludes 28th).

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'

response = requests.get(
    'https://sandbox.zefort.com/api/contracts/', 
    auth=(ZEFORT_APIKEY, ''),
    params={
        'receive_time': '20220425-20220428',
    })

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/?\
receive_time=20220425-20220428" \
     -u $ZEFORT_APIKEY:

You can easily modify this search to list all contracts created on and before or after a certain date.
Before: 'receive_time': '-20220425'
After: 'receive_time': '20220425-'

3. Sorting results

Search results can be sorted by different attributes of contracts.
- in front of the attribute name will reverse the order.

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'

response =  requests.get(
    'https://sandbox.zefort.com/api/contracts/',
    auth=(ZEFORT_APIKEY, ''),
    params={
        'status': 'review',
        'receive_time': '20220512-',
        'sort': 'end_date',
    })

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/?\
status=done&\
receive_time=20220512-&\
sort=end_date" \
     -u $ZEFORT_APIKEY:

4. Use case: Titles and ids of not reviewed contracts uploaded after a certain date

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'
URL = 'https://sandbox.zefort.com/api/contracts/'

response = requests.get(
    URL,
    auth=(ZEFORT_APIKEY, ''),
    params={
        'status': 'review',
        'receive_time': '20220512-',
        'minimal': True,
    })

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/?\
status=review&\
receive_time=20220512-&\
minimal=True" \
     -u $ZEFORT_APIKEY: