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:

EntityAvailable Filters
Submittalscreated_at, updated_at, name, assignee_user_id, watched_by, status, spec_section_id, creator_pm_group_id, submittal_type_id, submitting_pm_group_id
Projectscreated_at, updated_at, name,
Taskscreated_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 Userscreated_at, updated_at, name, email, last_name, first_name, phone_number, company, language, job_title, is_confirmed
Formscreated_at, updated_at, name, form_template_id, owner_user_id, creator_user_id, end_at, due_date
Form Templatescreated_at, updated_at, name, last_editor_user_id, creator_user_id, published_at, deleted_at, version
Sheetscreated_at, updated_at, name, last_editor_user_id, creator_user_id, floorplan_id, folder_id, file_name, deleted, at, version, meters_per_pixel
Markupscreated_at, updated_at, name, sheet_id, creator_user_id, last_editor_user_id, deleted_at
Floorplanscreated_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 NameFilter Operator
assignee_user_ideq
creator_pm_group_ideq
creator_user_ideq
floorplan_ideq
folder_ideq
form_template_ideq
is_confirmedeq
languageeq
last_editor_user_ideq
location_ideq
owner_user_ideq
sheet_ideq
spec_section_ideq
statuseq
status_ideq
submittal_type_ideq
submitting_pm_group_ideq
team_ideq
watched_byeq
companyeq, like
emaileq, like
file_nameeq, like
first_nameeq, like
job_titleeq, like
last_nameeq, like
nameeq, like
tageq, like
due_dategte, gt, lte, lt
end_atgte, gt, lte, lt
fixed_atgte, gt, lte, lt
published_atgte, gt, lte, lt
start_atgte, gt, lte, lt
verified_atgte, gt, lte, lt
meters_per_pixelgte, gt, lte, lt, eq
versiongte, gt, lte, lt, eq
created_atgte, gt, lte, lt
deleted_atgte, gt, lte, lt
updated_atgte, gt, lte, lt
phone_numbergte, 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