Verso API supports OData query parameters for filtering, sorting, and paginating results on all GET endpoints. This guide covers the available query options with practical examples.
Route Pattern
All examples use the Partner route pattern: /partners/5/tenants/10/{resource}. Replace with your actual partnerId and tenantId.
Query Parameters Overview
| Parameter | Description | Example |
|---|---|---|
$filter | Filter results by conditions | $filter=status eq 'Active' |
$orderby | Sort results | $orderby=created desc |
$select | Choose specific fields | $select=id,name,email |
$top | Limit number of results | $top=10 |
$skip | Skip first N results | $skip=20 |
$ prefix is optional
Both $filter and filter are accepted (same for $orderby/orderBy, $select/select, $top/top, $skip/skip). The API normalizes these automatically, so you can use whichever form your HTTP client supports best.
Filtering with $filter
Comparison Operators
| Operator | Description | Example |
|---|---|---|
eq | Equal | status eq 'Active' |
ne | Not equal | status ne 'Inactive' |
gt | Greater than | salary gt 50000 |
ge | Greater than or equal | age ge 18 |
lt | Less than | hours lt 40 |
le | Less than or equal | count le 100 |
String Functions
| Function | Description | Example |
|---|---|---|
contains | Contains substring | contains(name, 'John') |
startswith | Starts with | startswith(email, 'admin') |
endswith | Ends with | endswith(email, '@company.com') |
Logical Operators
| Operator | Description | Example |
|---|---|---|
and | Logical AND | status eq 'Active' and age gt 18 |
or | Logical OR | role eq 'Admin' or role eq 'Manager' |
not | Logical NOT | not contains(name, 'Test') |
Examples
Filter Active Employees
Filter by Division
Filter by Date Range
When using $filter in URLs, remember to URL-encode special characters. Most HTTP clients handle this automatically, but in raw URLs use %24filter instead of $filter.
Sorting with $orderby
Sort results by one or more fields in ascending (asc) or descending (desc) order.
Single Field
Sort by Name (Ascending)
Sort by Created Date (Descending)
Multiple Fields
Sort by Multiple Fields
Field Selection with $select
Return only specific fields to reduce response size.
Select Specific Fields
Response:
Code
Using $select can significantly improve performance by reducing payload size, especially for large datasets.
Pagination with $top and $skip
Limit Results
Get First 10 Results
Pagination Pattern
Page 1 (items 1-10)
Page 2 (items 11-20)
Page 3 (items 21-30)
Combined Queries
Combine multiple parameters for powerful queries:
Complex Query
This query:
- Filters for active employees
- Sorts by last name alphabetically
- Returns only id, firstName, and lastName
- Limits to 20 results
- Starts from the first result
Endpoint-Specific Examples
Query Users
Get Active Users
Query Payrun Jobs
Get Recent Completed Jobs
Query Payroll Results
Get Results for Specific Payrun
Query Payroll Result Sets (with Pagination)
For detailed wage type breakdowns, use /payrollresults/sets. The payrunJobId query parameter is required to scope results to a specific payrun job:
Get Result Sets for a Payrun Job (recommended)
With Pagination
Combine with Additional Filters
Dedicated Query Parameters
Some endpoints support dedicated query parameters as a shorthand for common filters. For example, ?payrunJobId=8 is equivalent to ?$filter=payrunJobId eq 8. When both are provided, they are combined with and.
Large Batches
For payrun jobs with 100+ employees, always use pagination ($top and $skip parameters) to avoid timeouts. Recommended page size: 50 results.
Best Practices
- Always paginate large datasets - Use
$topand$skipfor collections - Select only needed fields - Use
$selectto reduce payload size - Index-friendly filters - Filter on indexed fields when possible
- Combine filters efficiently - Use
andto narrow results early
Next Steps
- Error Handling - Handle query errors
- API Reference - Explore all endpoints
- Quickstart - Complete workflow example