ITONICS REST API: GET meta controls and filter options

What is it?

This article describes the meta controls and filters you can pass along with a GET request to slice, page, sort and narrow the data the ITONICS REST API returns.

This article is part of the ITONICS REST API series. For the overview, refer to Overview and getting started. The endpoints these controls apply to are listed in GET endpoints.

To efficiently slice and query your data set, you can pass multiple supported meta controls and filters along with your GET request, combining them using the & symbol, or using the ? character for single parameters, e.g. ?limit=100.

Check out our public Postman API collection:

This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.

In this article

• Standard pagination and ordering controls
• Field selection
• Dynamic data and filtering controls
• Rating filters and sorting
• Submission and campaign filters
• Element status filters

Standard pagination and ordering controls

These meta controls are universally available to manage data size, pagination, and sorting.

Field selection

Two meta controls narrow the response payload to the fields an integration actually needs, keeping responses small and avoiding the transfer of large values. Both are available on /api/{entity_type}.json, /api/{entity_type}/{id}.json, /api/user.json, and /api/user/{id}.json.

The two controls cannot be combined in a single request. Where both are provided, the request is rejected with a 400 Bad Request. A machine name that does not exist is likewise rejected with a 400 Bad Request.

System-mandatory fields are always part of the response. Listing one in fields_excluded does not produce an error - the field is retained. On element endpoints these are id, entity_type, title, abstract, and status. The auto-generated generated_id is returned by default and can be included or excluded like any other field. On the user endpoints they are uid and username.

Where neither control is provided, or the value is empty, the full payload is returned. Both controls combine with pagination, sorting, and all filter parameters. POST and PUT requests are unaffected.

Retrieve the available machine names via /api/entity_field_properties.json?type={entity_type} for elements and /api/user_field_properties.json for users.

Dynamic data and filtering controls

These controls are used for complex filtering based on field values, text search, or element properties. To retrieve the configuration details (including machine names) necessary for filtering by specific field values, use the /api/entity_field_properties.json?type={entity_type} GET endpoint of a particular {entity_type}. Note: Filter values must be URL encoded (e.g., spaces converted to %20).

Multiple filter parameters can be combined in a single request; an element is returned only when it satisfies every filter (AND logic). A filter parameter that is not recognised is rejected with a 412 Precondition Failed response.

Rating filters and sorting

Elements can be filtered and ranked by their rating values directly on the element endpoints /api/{entity_type}.json and /api/{entity_type}/{id}.json.

Both range parameters are optional and can be combined to define a closed range, or used individually for an open-ended threshold. The values are validated against the rating scale configured for the respective rating criteria; a value outside that scale is rejected, as is a maximum lower than the minimum. A rating_criteria value that does not exist is rejected.

To rank the result set by rating value, combine the filters with sort=average_decimal and direction. Sorting orders the result set without reducing it - use limit to cap the number of returned elements:

/api/itonics_trend.json?rating_criteria=rating_116_strategic_relevance&rating_criteria_average_min=3&sort=average_decimal&direction=DESC&limit=4

Note: The dedicated /api/entity_rating_info.json endpoint does not accept these parameters.

Submission and campaign filters

The submission and campaign GET endpoints support filtering on default and custom submission fields.

Filters combine with each other and with the existing camp_id parameter via AND logic. Where a campaign's configuration does not include a given custom field, the corresponding filter simply does not apply to that campaign.

Filtering and sorting submissions by rating

To rank submissions, use sort=five_star or sort=rating_criteria_average_decimal together with direction:

/api/itonics_idea.json?camp_id=20&five_star_min=4&sort=five_star&direction=DESC

Element status filters

These specific parameters filter elements based on their status or system flags.