Filtering
Filtering data from the API
Intro
As of September 2022, Fieldwire supports API filters on a select set of endpoints as query parameters. These filters should allow users to get just the information they need from the API without extra, unneeded records. This document will outline the available filters and endpoints that can be used. Filtering can be performed on one or more attributes as needed, and should appear in the parameters of the API call.
Note: this document assumes the user has some familiarity with the fieldwire API
Filter Structure
Fieldwire filters are constructed of 3 key parts:
- The Filter Name
- The Filter Operator
- The Filter Value
Each of these must be present in order for the API to properly return values, and proper syntax must be followed
Filter Name
The filter name defines which field the query will filter against. Some Fieldwire entities only support specific filter names. The full list of filterable entities and their filter names can be found in this table:
| Entity | Available Filters |
|---|---|
| Submittals | created_at, updated_at, name, assignee_user_id, watched_by, status, spec_section_id, creator_pm_group_id, submittal_type_id, submitting_pm_group_id |
| Projects | created_at, updated_at, name, |
| Tasks | created_at, updated_at, name, tag, status_id, location_id, team_id, owner_user_id, creator_user_id, start_at, end_at, due_date, fixed_at, verified_at, floorplan_id |
| Project Users | created_at, updated_at, name, email, last_name, first_name, phone_number, company, language, job_title, is_confirmed |
| Forms | created_at, updated_at, name, form_template_id, owner_user_id, creator_user_id, end_at, due_date |
| Form Templates | created_at, updated_at, name, last_editor_user_id, creator_user_id, published_at, deleted_at, version |
| Sheets | created_at, updated_at, name, last_editor_user_id, creator_user_id, floorplan_id, folder_id, file_name, deleted, at, version, meters_per_pixel, sheet_upload_id |
| Markups | created_at, updated_at, name, sheet_id, creator_user_id, last_editor_user_id, deleted_at |
| Floorplans | created_at, updated_at, name, tag |
Filter Operator
The filter operator defines the comparison that is made against the filter name. For example, a user can use the ‘eq’ operator with the ‘first_name’ filter name to find a user with a matching first name. Supported filter operators include:
- eq (equals)
- lt (less than)
- like (string match)
- gte (greater than or equals)
- lte (less than or equals)
The full list of filter names and their available operators can be found in the following table:
| Filter Name | Filter Operator |
|---|---|
| assignee_user_id | eq |
| creator_pm_group_id | eq |
| creator_user_id | eq |
| floorplan_id | eq |
| folder_id | eq |
| form_template_id | eq |
| is_confirmed | eq |
| language | eq |
| last_editor_user_id | eq |
| location_id | eq |
| owner_user_id | eq |
| sheet_id | eq |
| spec_section_id | eq |
| status | eq |
| status_id | eq |
| submittal_type_id | eq |
| submitting_pm_group_id | eq |
| team_id | eq |
| watched_by | eq |
| sheet_upload_id | eq |
| company | eq, like |
| eq, like | |
| file_name | eq, like |
| first_name | eq, like |
| job_title | eq, like |
| last_name | eq, like |
| name | eq, like |
| tag | eq, like |
| due_date | gte, gt, lte, lt |
| end_at | gte, gt, lte, lt |
| fixed_at | gte, gt, lte, lt |
| published_at | gte, gt, lte, lt |
| start_at | gte, gt, lte, lt |
| verified_at | gte, gt, lte, lt |
| meters_per_pixel | gte, gt, lte, lt, eq |
| version | gte, gt, lte, lt, eq |
| created_at | gte, gt, lte, lt |
| deleted_at | gte, gt, lte, lt |
| updated_at | gte, gt, lte, lt |
| phone_number | gte, gt, lte, lt |
Filter Value
The filter value is the string, date, UUID or integer used to find matching records according to the filter name and operator used.
Chaining all of these together, filtering on a single attribute will look like this:
filters[<filter_name>_<operator>]=[filter value]
Using Multiple Filters
Fieldwire API users can apply multiple filters to further refine results from the API. For example, with the following query, the user can filter for floorplans with the tag “foo” and with a created date after January 1st, 2022
/api/v3/projects/<project_id>/floorplans/?filters[tag_eq]=foo&filters[created_at_gt]=2022-01-01
API users can also apply multiple values to their queries to get results from an array of values for a particular resource. For example, with the following query, the user can filter for tasks with the status "requested" or "waiting" and get results where tasks match either status
/api/v3/projects/<project_id>/tasks/?filters[status_eq][]=requested&filters[status_eq][]=waiting
Updated about 1 month ago