Manipulating List results (filter, sort, search, paging, optional fields)

All listing endpoints provide query parameters for manipulating the results: searching (q), filtering (filter), sorting (sort), pagination (limit and offset) and optional fields (with).

Sorting

The GET Parameter sort accepts a string representing the sorting expression.
If you woud like to sort by the field 'name' ascending, the correct parameter would be 'sort=name'

Following are a few examples:

Sorting desired	Value of parameter 'sort'
name ASC	name
name DESC	-name
surname DESC, name ASC	-surname,name

Filtering

The GET Parameter filter accepts a JSON representing the filtering expression.

Assuming you would like to filter a list and only receive entries where the field currency equals to CHF your expression would be:

{"currency":"CHF"}

You can combine multiple expressions. For example listing all entries with currency CHF, and the contact_id being 99 your expression would be:

{
    "and":[
        {"currency":"CHF"},
        {"contact_id":99}
    ]
}
        

More complex combinations are also possible: (key1=a AND key2=b) OR key3=c

{
    "or":[
        {
            "and":[
                {"key1":"a"},
                {"key2":"b"}
            ]
        },
        {"key3":"c"}
    ]
}

key1="a" AND (key2="b" OR key3="c")

{
    "and":[
        {"key1":"a"},
        {
            "or":[
                {"key2":"b"},
                {"key3":"c"}
            ]
        }
    ]
}

key1="a" AND (key2="b" OR (key3="c" AND key4="d"))

{
    "and":[
        {"key1":"a"},
        {
            "or":[
                {"key2":"b"},
                {
                    "and":[
                        {"key3":"c"},
                        {"key4":"d"}
                    ]
                }
            ]
        }
    ]
}

Comparators can also be different to equaling. Following comparators are available, and are prepended to the value to be searched (not all comparators are available for all value types)

Comparator	Meaning
<	smaller than
<=	smaller or equals than
>	greater than
>=	greater or equals than
!	not equals to
~	approximately

Filtering for a contact whereby the value ACME is contained in its name would look the following:

GET https://api.smallinvoice.com/v2/receivables/invoices?filter={"name":"~ACME"}

Searching

Plain blind searches can be done by passing the string to be searched in the parameter q

It is possible to pass characters, words or sentences in this parameter, and the API will search by multiple fields and according to result relevance.

An example of searching invoices whereby we are seraching for an invoice containing the word 'Service' in general, would look like the following:

GET https://api.smallinvoice.com/v2/receivables/invoices?q=Service

Paging

Every listing endpoint accepts the two parameters limit and offset and has a maximum limit of 200 entries.

Using them together enables you to do simple paging. In every listing response you will furthermore receive the full URLs of the previous,next and last page (automatically calculating the correct offset).

An example for listing invoices with limit 100, showing records 101 - 200 would be:

GET https://api.smallinvoice.com/v2/receivables/invoices?limit=100&offset=100

Optional fields

Many listing endpoints do not output all available fields by default. If you wish to receive optional fields you can pass them comma separated in the query parameter with.

An example for listing invoices with the main address visible would be:

GET https://api.smallinvoice.com/v2/receivables/invoices?with=main_address