Filtering

The Bokio API supports powerful filtering capabilities through query parameters in GET requests. Filtering allows you to retrieve only the data that matches specific criteria, making your API calls more efficient and reducing the amount of data transferred.

How Filtering Works

Filters are applied using query parameters in the URL. The general syntax is:

GET /api/resource?query=property operator value

Not all properties in a resource are available for filtering. Please refer to each operation's documentation to see which properties can be filtered.

Filter Syntax

Basic Structure

• Property: The field you want to filter on (e.g., name, amount, createdDate)
• Operator: The comparison operator (see table below)
• Value: The value to compare against

URL Encoding

When constructing filter queries, remember to URL-encode special characters:

• Spaces: %20
• Equals: %3D (when part of the value)
• Ampersand: %26
• Pipe: %7C

Supported Operators

Examples by Data Type

String Filtering

Exact Match (==)

GET /api/customers?query=name%3D%3DJohn%20Doe

GET /api/customers?query=name==John Doe

Finds customers with the exact name "John Doe".

Not Equal (!=)

GET /api/invoices?query=status%21%3Ddraft

GET /api/invoices?query=status!=draft

Finds all invoices except those with status "draft".

Contains (~)

GET /api/customers?query=name%7EJohn

GET /api/customers?query=name~John

Finds customers whose name contains "John" (case-sensitive).

Number Filtering

Exact Match (==)

GET /api/customers?query=totalAmount%3D%3D1000

GET /api/customers?query=totalAmount==1000

Finds invoices with exactly 1000 in totalAmount.

Greater Than (>)

GET /api/invoices?query=totalAmount%3E500

GET /api/invoices?query=totalAmount>500

Finds invoices with totalAmount greater than 500.

Range Filtering

GET /api/invoices?query=totalAmount%3E%3D100%26%26totalAmount%3C%3D1000

GET /api/invoices?query=totalAmount>=100&&totalAmount<=1000

Finds invoices with totalAmount between 100 and 1000 (inclusive).

Date/DateTime Filtering

Exact Date (==)

GET /api/invoices?query=dueDate%3D%3D2025-01-15

GET /api/invoices?query=dueDate==2025-01-15

Finds invoices due on exactly January 15, 2025.

Date Range

GET /api/invoices?query=invoiceDate>=2025-01-01&&invoiceDate<2025-02-01

GET /api/invoices?query=invoiceDate%3E%3D2025-01-01%26%26invoiceDate%3C2025-02-01

Finds invoices with invoice date in January 2025.

Recent Records

GET /api/invoices?query=invoiceDate%3E2025-01-01

GET /api/invoices?query=invoiceDate>2025-01-01

Finds invoices with invoice date after January 1, 2025.

Combining Filters

AND Operations (&&)

Use && to combine multiple conditions that must all be true:

GET /api/invoices?query=status%3D%3Dpending%26%26totalAmount%3E100%26%26dueDate%3C2025-12-31

GET /api/invoices?query=status==pending&&totalAmount>100&&dueDate<2025-12-31

Finds pending invoices over 100 that are due before the end of 2025.

OR Operations (||)

Use || to combine conditions where any one can be true:

GET /api/invoices?query=status%3D%3Dpublished%7C%7Cstatus%3D%3Dpaid

GET /api/invoices?query=status==published||status==paid

Finds invoices that are either published or paid.

Common Use Cases

Financial Reports

# Invoices from Q1 2025 over 1000
GET /api/invoices?query=invoiceDate%3E%3D2025-01-01%26%26invoiceDate%3C2025-04-01%26%26totalAmount%3E1000

# Unpaid invoices with due date this month
GET /api/invoices?query=status%21%3Dpaid%26%26invoiceDate%3E%3D2025-01-01%26%26invoiceDate%3C2025-02-01

# Invoices from Q1 2025 over 1000
GET /api/invoices?query=invoiceDate>=2025-01-01&&invoiceDate<2025-04-01&&totalAmount>1000

# Unpaid invoices with due date this month
GET /api/invoices?query=status!=paid&&invoiceDate>=2025-01-01&&invoiceDate<2025-02-01

Customer Management

# Customers with Swedish VAT number
GET /api/customers?query=vatNumber%7ESE

# Private customers
GET /api/customers?query=type%3D%3Dprivate

# Customers with Swedish VAT number
GET /api/customers?query=vatNumber~SE

# Private customers
GET /api/customers?query=type==private

Journal Entries

# Entries for a date range where the title contains invoice
GET /api/journal-entries?query=date%3E%3D2025-01-01%26%26date%3C%3D2025-01-31%26%26title%7Einvoice

# Entries for a date range where the title contains invoice
GET /api/journal-entries?query=date>=2025-01-01&&date<=2025-01-31&&title~invoice

Troubleshooting

1. No results returned: Check that your filter values match the exact format and case of the data
2. Syntax errors: Ensure proper URL encoding of special characters
3. Unexpected results: Verify that you're using the correct operator for the data type
4. Performance issues: Consider if there are ways to reduce complexity of the filter