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

🔷 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
}

🔷 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

🔷 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