Guides

OData Query Parameters

Copy page

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.

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

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
 
curl -X GET "https://api.sandbox.verso.io/employees?\$filter=status eq 'Active'" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Division
 
curl -X GET "https://api.sandbox.verso.io/employees?\$filter=divisions/any(d: d eq 'Sales')" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Date Range
 
curl -X GET "https://api.sandbox.verso.io/payruns/jobs?\$filter=periodStart ge 2025-01-01T00:00:00Z and periodStart lt 2025-02-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting with $orderby

Sort results by one or more fields in ascending (asc) or descending (desc) order.

Single Field

Sort by Name (Ascending)
 
curl -X GET "https://api.sandbox.verso.io/employees?\$orderby=lastName asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort by Created Date (Descending)
 
curl -X GET "https://api.sandbox.verso.io/users?\$orderby=created desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Multiple Fields

Sort by Multiple Fields
 
curl -X GET "https://api.sandbox.verso.io/employees?\$orderby=lastName asc, firstName asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Field Selection with $select

Return only specific fields to reduce response size.

Select Specific Fields
 
curl -X GET "https://api.sandbox.verso.io/employees?\$select=id,identifier,firstName,lastName" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Code
 
[
  {
    "id": 1,
    "identifier": "[email protected]",
    "firstName": "Jean",
    "lastName": "Dupont"
  }
]

Pagination with $top and $skip

Limit Results

Get First 10 Results
 
curl -X GET "https://api.sandbox.verso.io/employees?\$top=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination Pattern

Page 1 (items 1-10)
 
curl -X GET "https://api.sandbox.verso.io/employees?\$top=10&\$skip=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Page 2 (items 11-20)
 
curl -X GET "https://api.sandbox.verso.io/employees?\$top=10&\$skip=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Page 3 (items 21-30)
 
curl -X GET "https://api.sandbox.verso.io/employees?\$top=10&\$skip=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Combined Queries

Combine multiple parameters for powerful queries:

Complex Query
 
curl -X GET "https://api.sandbox.verso.io/employees?\$filter=status eq 'Active'&\$orderby=lastName asc&\$select=id,firstName,lastName&\$top=20&\$skip=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

This query:

1. Filters for active employees
2. Sorts by last name alphabetically
3. Returns only id, firstName, and lastName
4. Limits to 20 results
5. Starts from the first result

Endpoint-Specific Examples

Query Users

Get Active Users
 
curl -X GET "https://api.sandbox.verso.io/users?\$filter=status eq 'Active'&\$orderby=lastName" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Payrun Jobs

Get Recent Completed Jobs
 
curl -X GET "https://api.sandbox.verso.io/payruns/jobs?\$filter=jobStatus eq 'Complete'&\$orderby=created desc&\$top=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Payroll Results

Get Results for Specific Payrun
 
curl -X GET "https://api.sandbox.verso.io/payrollresults?\$filter=payrunJobId eq 8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

1. Always paginate large datasets - Use $top and $skip for collections
2. Select only needed fields - Use $select to reduce payload size
3. Index-friendly filters - Filter on indexed fields when possible
4. Combine filters efficiently - Use and to narrow results early

Next Steps

• Error Handling - Handle query errors
• API Reference - Explore all endpoints
• Quickstart - Complete workflow example