Filter & sort

List operations on the OLIFY API are OData v4 compliant. Use the query options below to filter, sort, project, expand, and page results.

Not every list documents every option. $search in particular is available only on some lists — check the operation page before you send it.

Send Accept: application/json and the standard authentication and tenant headers on every list request.

Option	Purpose
`$filter`	Return records that satisfy an OData filter
`$orderby`	Sort records by one or more properties
`$select`	Return only selected properties
`$expand`	Include a related resource
`$count`	Include the total number of matching records
`$top`	Limit the number of returned records
`$skip`	Skip records for offset paging
`$search`	Full-text search, when the list documents `$search`

Property names in $filter, $orderby, $select, and $expand are camelCase, such as localityId, name, and locality.

Response shape

Every list response contains a value array:

{
  "value": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "code": "AHU-01",
      "name": "Air handling unit"
    }
  ]
}

Add $count=true to include the total number of records that match the filter and search:

{
  "value": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "code": "AHU-01",
      "name": "Air handling unit"
    }
  ],
  "count": 42
}

count is calculated before $top and $skip are applied. It therefore represents the total matching result set, not the size of the current page. If $count is omitted, the response does not include count.

The OLIFY API uses count, not the standard OData @odata.count property.

Paging with `$top` and `$skip`

Use $top as the page size and $skip as the zero-based offset:

GET https://api.olify.io/assets?$orderby=name&$top=50&$skip=100&$count=true
Authorization: Bearer {access_token}
Olify-Tenant-Id: {tenant_id}
Accept: application/json

For a zero-based pageIndex, calculate the offset as:

$skip = pageIndex * $top

For example, with a page size of 50, page indexes 0, 1, and 2 use $skip values 0, 50, and 100.

Include $orderby when paging so that successive requests use an explicit sort order.

The host-wide maximum for $top is 10000. An operation can enforce a lower per-action maximum. A value above the applicable maximum is rejected with an OData error containing:

The limit of '{max}' for Top query has been exceeded

Choose a bounded page size and continue requesting pages until value contains fewer records than $top, or until $skip + value.length reaches count when $count=true is present.

Filtering with `$filter`

$filter supports OData 4 comparison and logical operators.

Comparison operators

Operator	Meaning
`eq`	Equal
`ne`	Not equal
`gt`	Greater than
`ge`	Greater than or equal
`lt`	Less than
`le`	Less than or equal

Logical operators

Operator	Meaning
`and`	Both expressions must be true
`or`	Either expression may be true
`not`	Negates an expression

Use single quotes for string literals:

$filter=name eq 'Main building'

Write GUID literals without quotes:

$filter=localityId eq 11111111-1111-1111-1111-111111111111

Combine expressions with logical operators and parentheses:

$filter=(localityId eq 11111111-1111-1111-1111-111111111111) and (name ne 'Retired pump')

String functions

The following common OData string functions are available:

Function	Example
`contains`	`contains(name,'pump')`
`startswith`	`startswith(code,'AHU')`
`endswith`	`endswith(name,'room')`
`tolower`	`tolower(name) eq 'main building'`
`toupper`	`toupper(code) eq 'AHU-01'`

This request returns assets in one locality whose names contain pump:

GET https://api.olify.io/assets?$filter=localityId%20eq%2011111111-1111-1111-1111-111111111111%20and%20contains(name,%27pump%27)&$orderby=name&$top=50
Authorization: Bearer {access_token}
Olify-Tenant-Id: {tenant_id}
Accept: application/json

For command-line requests, use --data-urlencode so spaces, quotes, and parentheses are encoded correctly:

curl -sS -G 'https://api.olify.io/assets' \
  --data-urlencode "\$filter=localityId eq 11111111-1111-1111-1111-111111111111 and contains(name,'pump')" \
  --data-urlencode '$orderby=name' \
  --data-urlencode '$top=50' \
  --data-urlencode '$count=true' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Olify-Tenant-Id: $TENANT_ID" \
  -H 'Accept: application/json'

Sorting with `$orderby`

Sort in ascending order by naming the property:

$orderby=name

Use desc for descending order:

$orderby=name desc

Separate multiple sort expressions with commas:

$orderby=name,code desc

A complete sorted request:

GET https://api.olify.io/localities?$orderby=name&$top=100&$skip=0
Authorization: Bearer {access_token}
Olify-Tenant-Id: {tenant_id}
Accept: application/json

Selecting properties with `$select`

Use $select to reduce each result to the properties your application needs:

$select=id,code,name

curl -sS -G 'https://api.olify.io/maintenance-tickets' \
  --data-urlencode '$select=id,code,name' \
  --data-urlencode '$orderby=name' \
  --data-urlencode '$top=25' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Olify-Tenant-Id: $TENANT_ID" \
  -H 'Accept: application/json'

Use $expand to include a related resource. For example, include each asset's locality:

$expand=locality

You can combine $expand with $select:

GET https://api.olify.io/assets?$select=id,code,name,locality&$expand=locality&$orderby=name&$top=20
Authorization: Bearer {access_token}
Olify-Tenant-Id: {tenant_id}
Accept: application/json

curl -sS -G 'https://api.olify.io/assets' \
  --data-urlencode '$select=id,code,name,locality' \
  --data-urlencode '$expand=locality' \
  --data-urlencode '$orderby=name' \
  --data-urlencode '$top=20' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Olify-Tenant-Id: $TENANT_ID" \
  -H 'Accept: application/json'

Full-text search with `$search`

Some list operations accept $search. When they do, the operation page documents the $search query parameter.

$search is a simple query string. It does not implement the OData $search expression language — supply search text directly, without OData search operators.

GET https://api.olify.io/inspections?$search=fire%20safety&$orderby=name&$top=20&$count=true
Authorization: Bearer {access_token}
Olify-Tenant-Id: {tenant_id}
Accept: application/json

curl -sS -G 'https://api.olify.io/inspections' \
  --data-urlencode '$search=fire safety' \
  --data-urlencode '$orderby=name' \
  --data-urlencode '$top=20' \
  --data-urlencode '$skip=0' \
  --data-urlencode '$count=true' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Olify-Tenant-Id: $TENANT_ID" \
  -H 'Accept: application/json'

Combining query options

Query options can be combined in one request. The following example filters assets by locality and name, sorts them, selects four properties, and retrieves the second page with a total count:

curl -sS -G 'https://api.olify.io/assets' \
  --data-urlencode "\$filter=localityId eq 11111111-1111-1111-1111-111111111111 and startswith(name,'Air')" \
  --data-urlencode '$orderby=name' \
  --data-urlencode '$select=id,code,name,localityId' \
  --data-urlencode '$top=50' \
  --data-urlencode '$skip=50' \
  --data-urlencode '$count=true' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Olify-Tenant-Id: $TENANT_ID" \
  -H 'Accept: application/json'

Malformed expressions, unsupported options, and values above the applicable $top limit return OData errors. Send only the options documented on the operation and on this page.

On this page