Search for form entries

You can use the FormFlow API to search for form entries using a wide variety of filters, queries, and options.

Entries Search Parameters

These query string parameters can be added to refine a search to the /formsapi/public/search/entries endpoint. All responses are paged. All parameters are optional.

• query: A text-based query for searching all data associated with a form. This includes searching against all meta-data (e.g. status, state) and all form field data. Stemming is not supported. Wildcards are supported (e.g. use box* to find box, boxes, boxing) 
• pageNumber: Used for the paged response. Indicates the starting page of the returned data. If not set uses the default 1 for first page.
• pageSize: Used for the paged response. Indicates how many items to return. Default is 20. 
• form: The form ID, if you wish to only search for entries tied to a specific form.
• archived: A boolean to indicate if ONLY archived entries should be returned.
• overdue: A boolean to indicate if ONLY overdue entries should be returned.
• status: Used to filter by status. Can be 'open', 'closed' or 'all'. If empty, 'open' is used.
• statusId: For a specific custom status tied to a form. This value can be found from getting the schema for a form via /formsapi/public/form/{formId}
• sortDirection: Order for sorted results. Can be asc or desc for ascending or descending.
• sortOn: The name of the field to sort on. Supported values are (note all lower case):
  • duedate, submitteddate, title, state, assignee, submitter, entrynumber
  • Also supports an integer corresponding to a field Id for a specific form (e.g. sortOn=123)
• sortRandom: Sorted results are completely randomized. 
• sortSeed: To support paging you can specify the seed so that the results are randomized the same way across all pages.
• title: This is a query for the title of the form entry. 
• state: This is a query for the state of the form entry.
• assignee: An array of user IDs to filter for entries assigned to specific users.
• submitter: An array of user IDs to filter for entries submitted by specific users.
• dueDate: A string to search for form entries due at a specific time using the supported format (see Dates in search).
• dateSubmitted: A string to search for form entries submitted at a specific time using the supported format (see Dates in search).

Search on specific field values

You are also able to search and filter form entry results using special query parameters that indicate the form or option to use. 

Form field text query

Using the format field{fieldId} you can specify a text query to search for in field entries. The field ID can be found from the schema for a form using the endpoint /formsapi/public/form/{formId}.

The text query will perform a tokenized search. So all terms in both the query and the field will be transformed into a list of lower case strings and compared against each other. If there is even a single token match then it returns in the search.

You can use double quotes to create phrases (e.g. field123="text entry") to search for if you need to be more specific.

NOTE: No stemming or partial word comparison is supported. To achieve this you can use wildcards (e.g. box* to match box, boxing, boxes, etc...).

Examples:

Option field exact match

Using the format option{fieldId} you can specify an optionId as a value and filter the entries for only items that have that exact option selected for that field.

For example, option123=456 means "Only return entries that have the option 456 selected in field 123". Both the field Ids and their available options are found from the schema for a form using the endpoint /formsapi/public/form/{formId}.

For fields that support an "other" option, you can use the format option123=other. This will return all entries where the user has selected Other for the field with id 123. To do text-based searching on Other field values you must use the Form field text query method described in the previous section.

Dates in search

Date filters use a string that is in a specific format to allow for a variety of ranges. They must be in the exact format or there will be errors. 

Supported format

All dates should be in the format YYYY-MM-DD. For example, 2021-04-15. 

Single day

The date field should simply be a single date in the supported format. 

After a certain day

Prefix a date in the supported format with the keyword after (e.g. after2021-04-15).

Before a certain day

Prefix a date in the supported format with the keyword before (e.g. before2021-04-15).

A date range

Use the keyword to in between two dates in the supported format (e.g. 2021-01-01to2021-04-15).