Skip to main content

Filtering and Sorting

Learn how to filter and sort API responses using query parameters.

Overview​

Debitura APIs support powerful filtering and sorting capabilities on list endpoints. This allows you to query exactly the data you need and receive it in the desired order.

Filtering​

Filter results using query parameters that match resource fields. Different field types support different operators.

Basic Filtering​

Filter by exact match using field names as query parameters:

GET /api/v1/cases?status=active
GET /api/v1/cases?country=DK

Multiple Filters​

Combine multiple filters - all conditions must match (AND logic):

GET /api/v1/cases?status=active&country=DK

Filter Operators​

For advanced filtering, use operator suffixes on field names:

Comparison Operators​

  • field[eq] - Equals (default if no operator)
  • field[ne] - Not equals
  • field[gt] - Greater than
  • field[gte] - Greater than or equal
  • field[lt] - Less than
  • field[lte] - Less than or equal

String Operators​

  • field[contains] - Contains substring (case-insensitive)
  • field[starts_with] - Starts with prefix
  • field[ends_with] - Ends with suffix

List Operators​

  • field[in] - Value is in list (comma-separated)
  • field[nin] - Value is not in list

Date/Time Operators​

  • field[before] - Before specified date/time
  • field[after] - After specified date/time

Filter Examples​

# Amount greater than 1000
GET /api/v1/cases?amount[gt]=1000

# Created in the last 30 days
GET /api/v1/cases?created_at[after]=2025-01-01

# Status is either active or pending
GET /api/v1/cases?status[in]=active,pending

# Customer name contains "Acme"
GET /api/v1/cases?customer_name[contains]=Acme

# Amount between 1000 and 5000
GET /api/v1/cases?amount[gte]=1000&amount[lte]=5000

Sorting​

Control the order of results using the sort parameter.

Basic Sorting​

Sort by a single field in ascending order:

GET /api/v1/cases?sort=created_at

Descending Order​

Prefix field name with - for descending order:

GET /api/v1/cases?sort=-created_at

Multiple Sort Fields​

Sort by multiple fields (comma-separated). Fields are applied in order:

GET /api/v1/cases?sort=-priority,created_at

This sorts by priority descending, then by created_at ascending for ties.

Sortable Fields​

Not all fields are sortable. Common sortable fields include:

  • created_at - Creation timestamp
  • updated_at - Last modification timestamp
  • amount - Monetary amounts
  • due_date - Due dates
  • status - Status values (using predefined order)
  • priority - Priority level

See individual API endpoint documentation for available sortable fields.

Combining Filtering, Sorting, and Pagination​

You can combine all query capabilities in a single request:

GET /api/v1/cases?status=active&amount[gt]=1000&sort=-created_at&limit=50&cursor=abc123

This request:

  1. Filters for active cases
  2. With amount greater than 1000
  3. Sorted by creation date (newest first)
  4. Returns 50 results per page
  5. Starting from the cursor position

Best Practices​

Performance Optimization​

  • Index-friendly filters - Filter on indexed fields when possible (id, created_at, status)
  • Specific filters - Use precise filters to reduce result set size
  • Limit results - Always use pagination with appropriate page sizes

Filter Construction​

  • URL encoding - Properly encode special characters in filter values
  • Type matching - Ensure filter values match field types (numbers, dates, strings)
  • Date formats - Use ISO 8601 format for dates (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)

Common Patterns​

# Recent high-value active cases
GET /api/v1/cases?status=active&amount[gte]=5000&created_at[after]=2025-01-01&sort=-amount

# Search customer names
GET /api/v1/customers?name[contains]=smith&sort=name

# Cases due soon
GET /api/v1/cases?due_date[before]=2025-02-01&status[in]=pending,active&sort=due_date

Field-Specific Filtering​

Different endpoints support different filterable fields. Check the specific API reference for:

  • Available filter fields
  • Supported operators per field
  • Field data types and formats
  • Special filter behaviors

Error Handling​

Common filtering/sorting errors:

  • invalid_filter_field - Field doesn't support filtering
  • invalid_filter_operator - Operator not supported for field type
  • invalid_filter_value - Value doesn't match expected format
  • invalid_sort_field - Field doesn't support sorting
  • Pagination - Navigate through filtered results
  • Error Handling - Handle filter validation errors
  • API endpoint references for field-specific filter options