Filtering

Intro

As of September 2022, Fieldwire now 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
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
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
company	eq, like
email	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