Dynamic filters

Refine the results of any GET query by adding filters directly to the request URL.

⚠️
Availability: Dynamic filters are not enabled on all endpoints. You can only use them on endpoints that explicitly indicate filter support in their reference documentation. Check each endpoint's page to verify whether it supports filters and which fields are available.

🔷 How do filters work?

All filters applied in a single request are evaluated using AND logic. This means the results returned will only include records that match all conditions simultaneously.

🔷 Filter structure

Each filter consists of three parts: the field name, the comparison operator, and the desired value.

Standard format:

field[operator]=value

Example: Search for work orders with status "open" and cost greater than or equal to 100:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100

🔷 Available operators

Below are the allowed operators grouped by the data type of the field (text, numbers, or dates).

Operator	Description	Supported data types
eq	Exact equality	text, number, date, boolean
neq	Not equal to	text, number, date, boolean
gt	Greater than	number, date
gte	Greater than or equal to	number, date
lt	Less than	number, date
lte	Less than or equal to	number, date
like	Partial search (contains text)	text
between	Range between two values	number, date
in	List of values (comma-separated)	numbers only

🔷 How operators work

Equality and Difference

Searches for an exact match (eq) or excludes specific records (neq).

Examples:

?id[eq]=3 (Only the record with ID 3)
?id[neq]=1 (All records except ID 1)
?status[eq]=open (Work orders with status "open")

🔷 Multiple filters

Combine multiple conditions in a single request using the & symbol. The system returns only records that match all conditions at once.

Example: Search for work orders that are not #3, with cost less than 500 and description containing "urgent":

GET https://app.fracttal.com/api/work_orders?id[neq]=3&cost[lt]=500&description[like]=urgent

🔷 Date filtering

Dates are one of the most commonly used filters. The API expects dates in ISO 8601 format: YYYY-MM-DDTHH:MM:SS±UTC.

Filter work orders created in January 2024:

GET https://app.fracttal.com/api/work_orders?date[between]=2024-01-01T00:00:00-05,2024-01-31T23:59:59-05

Alternative to between using two separate filters. Filter work orders between March 1 and June 30, 2024:

GET https://app.fracttal.com/api/work_orders?date[gte]=2024-03-01T00:00:00-05&date[lte]=2024-06-30T23:59:59-05

This approach is useful when you need to combine a date range with additional filters.

The + sign in a timezone must be encoded as %2B in the URL. If not encoded, the server interprets it as a space and the query fails.

❌ Incorrect:

?date[gt]=2024-01-01T00:00:00+02

✅ Correct:

?date[gt]=2024-01-01T00:00:00%2B02

🔷 Complete request and response example

Below is a real request with applied filters and the possible responses.

Request: Get work orders with status "open" and cost greater than or equal to 100:

curl -X GET "https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "wo_folio": "WO-001234",
      "description": "Preventive maintenance hydraulic pump",
      "status": "open",
      "cost": 250.00,
      "date": "2024-03-15T10:30:00-05"
    },
    {
      "wo_folio": "WO-001289",
      "description": "Electrical system inspection north plant",
      "status": "open",
      "cost": 180.50,
      "date": "2024-03-20T08:00:00-05"
    }
  ],
  "total": 2
}

Example: using the like operator on a numeric field (cost):

curl -X GET "https://app.fracttal.com/api/work_orders?cost[like]=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "field": "cost",
      "operator": "like",
      "error": "The 'like' operator is not compatible with numeric fields."
    }
  ]
}

🔷 Common errors and solutions

Error	Cause	Solution
Incompatible operator with data type	Using `like` on a numeric field or `in` on a text field	Check the operators table and verify the supported data types for each operator
Too many filters	Sending more than 20 filters in a single request	Reduce the number of conditions or split the query into multiple requests
Too many values in `in`	Sending more than 100 values in an `in` list	Split the values into multiple requests with lists of 100 or fewer
Incorrect date format	Not following the ISO 8601 format (`YYYY-MM-DDTHH:MM:SS±UTC`)	Use the correct format: `2024-01-01T00:00:00-05`
Timezone with unencoded `+`	Writing `+02` instead of `%2B02` in the URL	Encode the `+` sign as `%2B`
Incorrect `between` values	Sending more or fewer than 2 comma-separated values	Make sure to send exactly two values: `?field[between]=min,max`

🔷 Filterable fields per endpoint

📌
Not all endpoints support the same filterable fields. The available fields depend on the resource you are querying. Check the reference documentation for each endpoint to find out which specific fields it accepts as filters.
For example:

Work orders (/work_orders): status, cost, date, description, among others.

Assets (/items): code, description, status, among others.

Meters (/meters): code, serial, among others.

🔷 Sorting and pagination

Filters can be combined with sorting and pagination parameters to control results precisely.

Available parameters:

Parameter	Description	Example
`sort`	Field to sort results by	`sort=date`
`order`	Sort direction: `asc` (ascending) or `desc` (descending)	`order=desc`
`page`	Results page number	`page=1`
`limit`	Maximum number of records per page	`limit=50`

Complete example: Get work orders with status "open", sorted by date descending, showing 20 results per page:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&sort=date&order=desc&page=1&limit=20

🔷 Fracttal context examples

Filter by status and date range:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&date[gte]=2024-01-01T00:00:00-05&date[lte]=2024-03-31T23:59:59-05

Search by description and minimum cost:

GET https://app.fracttal.com/api/work_orders?description[like]=preventive&cost[gte]=500

Search assets whose description contains "pump":

GET https://app.fracttal.com/api/items?description[like]=pump

Filter active assets excluding a specific code:

GET https://app.fracttal.com/api/items?status[eq]=ACTIVE&code[neq]=AST-0001

Query meter readings by date range:

GET https://app.fracttal.com/api/meters_reading?date[between]=2024-01-01,2024-06-30

Filter meters by asset code:

GET https://app.fracttal.com/api/meters?code[eq]=MET-0042

Filter requests by status and creation date:

GET https://app.fracttal.com/api/work_requests?status[eq]=PENDING&date[gte]=2024-06-01T00:00:00-05

Search requests whose description contains "electrical":

GET https://app.fracttal.com/api/work_requests?description[like]=electrical

🔷 Important considerations

💡
Validation rules

Condition limit: A maximum of 20 filters per request is allowed.

List limit (IN): The in operator allows a maximum of 100 values per list.

Compatibility: Make sure to use the correct operator for the data type. For example, trying to use like on a price field or in on a description field will generate a validation error.

Special characters in dates: When filtering by dates that include timezones with the plus sign (+), it must be written as %2B.

Correct: ?date[gt]=2024-01-01T00:00:00%2B02

Dynamic filters

🔷 How do filters work?

🔷 Filter structure

🔷 Available operators

🔷 How operators work

Equality and Difference

Partial search

Magnitude comparisons

Value ranges

Multiple selection

🔷 Multiple filters

🔷 Date filtering

🔷 Complete request and response example

🔷 Common errors and solutions

🔷 Filterable fields per endpoint

🔷 Sorting and pagination

🔷 Fracttal context examples

🔷 Important considerations