Filters and sorting

Filters

Filtering of collections requires the use of the filter parameter. The filters allow you to narrow down your request to obtain the most accurate results.

Filter Types

• string – enclosed in single quote characters
• number
• date – enclosed in single quote characters and provided in yyyy-mm-dd format (for example 1966-Jul-30) unless system configuration requires otherwise, in which case the appropriate date format will have been provided by Phlexglobal.

All dates should be provided in the format dd-MMM-yyyy (for example 30-Jul-1966) unless the system has been configured otherwise, in which case the appropriate date format will have been provided by Phlexglobal.

Add filters to your request

There are usually two ways filters are added to your request:

1. You can append them to your URI address or insert the parameters if possible.
2. You need to use them within the body of your request.

note

The information whether you need to append filters or specify them in the body of the request is to be found in Api Reference. Look for the request in which you are interested and if contains the information about the request body, then you must use it. If not, append the filters to your URI. As a rule GET and PUT requests oriented towards downloading the information need appending the filters and PUT requests oriented towards amending resources use the request body. Note there may be exceptions to this rule.

1. How to append filters to URI?

FIlters consist of a series of expressions which can be grouped with a grouping operator () to control the evaluation order. To append the filters use the structure:

?filter=value in (‘value’)

You can use more than one filter, for example:

GET https://{client}-api.phlextmf.com/documents/v5/documents?filter=protocol in ('TestProtocol1')&limit=1

How to connect multiple filters?

You can connect multiple filters using either "and" or "&":

• and – connects multiple values for various filters, e.g.:

GET https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') and Transmitter in ('[email protected]') 

This request targets all the documents filed by the specific Transmitter ('[email protected]') within the specified protocol (TestProtocol1).

• & - connects various parameters while filtering them separately, e.g.:

GET https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') & Transmitter in ('[email protected]')

It finds all the documents filed under the specified protocol ('TestProtocol1') and all the documents filed by the specified Transmitter ('[email protected]').

tip

If you’d like to know which parameters you can append, you can check the parameters within the response in which you are interested. For example, the following request:

GET https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') 

returns the following result (the below is only the excerpt):

{
            "id": 900000000279,
            "filename": "AOJ-900000000279-D-doc1",
            "nativeFileName": "AOJ-900000000279-D-doc1-original.pdf",
            "fileSize": 388468,
            "mimeType": "application/pdf",
            "metadata": [

Therefore, you may filter by "id", "filename", "nativeFileName" etc.

note

Not all parameters may be the supported filter types.

2. How to use filters in the body of the request

All filters which can be used in the body of the request of the specific API call, can be found in Api Reference.

note

You do not need to use all the parameters, delete the redundant values.

Filter Operators

Filter operators enable you to point to specific values you would like to obtain. Three main filter operators can be distinguished:

Comparison Operators

Operator	Description	Example
eq	Equal. Only the exact match will be displayed. Applies to strings, dates, numbers.	name eq 'John Smith’
ne	Not equal. This element will be excluded from your search.Applies to strings, dates, numbers.	company ne 'Phlexglobal'
gt	Greater than. Applies to dates, numbers only.	pagecount gt 20
ge	Greater than or equal. Applies to dates, numbers only.	pagecount ge 10
lt	Less than. Applies to dates, numbers only.	pagecount lt 10
le	Less than or equal. Applies to dates, numbers only.	pagecount le 100
in	In. Apples to strings, dates, numbers.	company in ('Phlexglobal', 'NSE')

Logical Operators

Operator	Description	Example
and	Combine two operators to recive a receive a result for both values conjointly	pagecount le 200 and pagecount gt 20
&	Combine two operators to receive a result for both values separately	pagecount le 200 and pagecount gt 300
or	Combine two operators to receive results for one or both of them. Note: this can't be used with the Documents API.	pagecount le 20 or pagecount gt 200
not	Exclude the element from the search	not pagecount le 35

Functional Operators

Operator	Description	Example
contains	Contains (like). Applies to strings only.	contains(protocol, 'test')
startswith	Starts with. Applies to strings only.	startswith(protocol, 'test')
endswith	Ends with. Applies to strings only.	endswith(protocol, 'test')

Grouping Operators

Operator	Description	Example
Precedence grouping		(priority eq 1 or company eq 'Phlexglobal') and pagecount gt 20 date gt '2016-04-20' and protocol eq 'PG-001' protocol eq 'PG-001' and site eq '0001'

Rate limiting/thresholds

There is currently no limit to the number of requests a user can make.

URL Length

Due to compatibility issues, URLs over 2000 characters long must be avoided. Any received request longer than 2000 must respond with a 414 (URI Too Long) status code. If you need multiple values for multiple filters of varying length (such as for document searching) use the POST verb in preference to a GET to avoid potentially exceeding the URL length.

Filtering errors

If your request is not successful, the JSON response body will include an array of validation/error messages. For example:

• 400 BAD REQUEST, "message": "Unsupported filter field." - the filter type you have chosen is not supported and cannot be used.
• 400 BAD REQUEST, "message": "Filters are required" - at least one filter must be obligatorily included in the request otherwise the request will not be executed correctly.
• 400 BAD REQUEST, message "message": "Syntax error at position 28 in 'protocol in 'TestProtocol1')'." - the message points out the user error made in the request, in this case its a missing bracket before the protocol name.

To find out more about the errors, see Managing API requests and responses

Examples for filtering documents

1. GET request. Look for the relevant artifact within the specific protocol

https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') and Artifact in ('01.01.01 Trial Master File Plan')

2. GET request. Look for the documents submitted to the system for the particular protocol on the particular date.

https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') and DateReceived in ('2024-11-07')

3. GET request. Look for a list of documents with the specific status for a given protocol.

To specify the status you need to use the ProcessingStatusId and use the number that corresponds to the status name. For example:

https://{client}-api.dev.phlextmf.net/documents/v5/documents?filter=protocol in ('TestProtocol1') and ProcessingStatusId in ('500')

In the above request you are looking for all the documents for TestProtocol1 which are currently at the Final status, i.e. 500, please see the table below.

Table showing the selected processing status ids with their corresponding status names.

ProcessingStatusId	Status Name
0	New
5	Placeholder
7	Verifying file
12	Errored
32	Converting
39	Incomplete
40	Submitted
41	Fingerprinting
42	Duplicate Detection
43	Duplicate Review
55	Index
70	QC
110	Deleted
500	Final
550	Quality Review
560	Quality Check
600	QC Complete