Copy page

Guides

OData Query Parameters

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

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?filter=status eq 'Active'" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?filter=divisions/any(d: d eq 'Sales')" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/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

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?orderBy=lastName asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/users?orderBy=created desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Multiple Fields

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?orderBy=lastName asc, firstName asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Field Selection with select

Return only specific fields to reduce response size.

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/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

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?top=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination Pattern

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?top=10&skip=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?top=10&skip=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/employees?top=10&skip=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Combined Queries

Combine multiple parameters for powerful queries:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/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

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/users?filter=status eq 'Active'&orderBy=lastName" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Payrun Jobs

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payruns/jobs?filter=jobStatus eq 'Draft'&orderBy=created desc&top=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Payroll Results

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults?filter=payrunJobId eq 8" \
  -H "Authorization: Bearer YOUR_API_KEY"

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:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8&top=50&skip=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8&filter=status eq 'Active'" \
  -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