Querying with OData

Collection endpoints in the Partner API support OData query options. Rather than retrieving everything and filtering in your own code, you can ask the API for exactly the records and fields you want.

This matters for more than convenience: filtering server-side keeps responses small, reduces the number of calls you make, and avoids pulling data you have no use for.

Supported query options

Option	Description
`$filter`	Returns only records matching a condition.
`$select`	Returns only the properties you name.
`$orderby`	Sorts the results.
`$top`	Returns only the first n results.
`$skip`	Skips the first n results.
`$count`	Includes a count of matching results in the response.
`$expand`	Expands related entities inline.

Combine them with &, as ordinary query string parameters.

Filtering

$filter takes a Boolean expression using these operators:

Operator	Meaning
`eq`	Equal
`ne`	Not equal
`gt`	Greater than
`ge`	Greater than or equal
`lt`	Less than
`le`	Less than or equal
`and`	Both conditions
`or`	Either condition

Documents created after 1 January 2023:

GET /v1/documents?$filter=CreatedOn gt 2023-01-01T00:00:00.000Z

Companies registered before a date:

GET /v1/companies?$filter=DateRegistered le 2023-01-01T00:00:00.000Z

Dates are UTC and use ISO 8601 format.

The ? before the first query option is required. /v1/documents$filter=... is not a valid URL and will not filter anything.

Paging

Use $top and $skip together to page through a large collection:

GET /v1/documents?$top=50
GET /v1/documents?$top=50&$skip=50
GET /v1/documents?$top=50&$skip=100

Pair paging with $orderby so the ordering is stable between requests. Without it, records can appear on two pages or none.

GET /v1/documents?$orderby=CreatedOn&$top=50&$skip=50

Sorting

GET /v1/documents?$orderby=CreatedOn desc

Add asc or desc; ascending is the default.

Selecting fields

Return only what you need:

GET /v1/companies?$select=CompanyId,Name,ACN

Combining options

Ten most recently created documents, newest first, with only a few fields:

GET /v1/documents?$filter=CreatedOn gt 2024-01-01T00:00:00.000Z&$orderby=CreatedOn desc&$top=10&$select=DocumentId,DocumentName,CreatedOn

URL encoding

Query values containing spaces, colons or other reserved characters must be percent-encoded. Most HTTP libraries do this for you if you pass query parameters as values rather than building the URL by hand — which is the safer approach with OData, since filter expressions contain spaces by design.

Practical guidance

Filter by date on scheduled jobs. If you poll for new records, filter on CreatedOn or LastModifiedOn since your last run rather than retrieving everything and comparing locally.
Page rather than requesting everything. Large unbounded collections are slow for you and expensive for us.
Use $select when you only need a few fields. Some models are large.

API structure — endpoints and response formats.
Accessing child accounts — scoping queries to a child account.