The filter query parameter

You can narrow which resources are returned using the filter keyword followed by one or more criteria. The criteria are specified using the following syntax:

filter=field:op:value

where:

  • field is the name of a filterable field
  • op is one of the comparison operators from the following table
  • value is the value to compare
op value Meaning Example using the GET /activities endpoint Returns activities where...
eq Equal to ?filter=escalated:eq:true ...​the escalated field equals true
ne Not equal to ?filter=escalated:ne:true ...​the escalated field equals false
lt Less than ?filter=dueDate:lt:2020-05-11T07::00::00.​000Z ...​the due date is less than (before) May 11, 2020.
gt Greater than ?filter=dueDate:gt:2020-05-11T07::00::00.​000Z ...​the due date is greater than (after) May 11, 2020.
le Less than or equal ?filter=dueDate:le:2020-05-11T07::00::00.​000Z ...​the due date is less than or equal to (on or before) May 11, 2020.
ge Greater than or equal ?filter=dueDate:ge:2020-05-11T07::00::00.​000Z ...​the due date is greater than or equal to (on or after) May 11, 2020.
in In ?filter=priority:in:urgent,high ...​the priority is either urgent or high
ni Not in ?filter=priority:ni:urgent,high ...​the priority is neither urgent nor high
sw Starts with ?filter=subject:sw:Contact%20claimant ...​the subject starts with the string "Contact claimant"
cn Contains ?filter=subject:cn:Contact%20claimant ...​the subject contains the string "Contact claimant"

The query parameter is passed as part of a URL. Therefore, special conventions must be used for certain types of characters to ensure the URL can be parsed correctly.

  • Specify strings without surrounding quotes.
  • If a string has a space in it, use the URL encoding for a space (%20). (For example, "subject starts with 'Contact claimant'" is specified as filter=subject:sw:Contact%20claimant)
  • If a string has a colon (:) in it, use two colons (::) in the URL. The first colon acts as an escape character. (For example, "subject starts with 'Urgent: Information needed'" is specified as ?filter=subject:sw:Urgent::%20Information%20needed)
  • Specify Booleans as either true or false. (For example, "escalated is true" is specified as ?filter=escalated:eq:true)
  • Date and datetime fields must be specified as an ISO-8601 datetime value. All datetime fields can accept either date values or datetime values. For datetime values, the colons in the value must be expressed as "::". For example, "due date is less than 2020-04-03T15:00:00.000Z" is specified as ?filter=dueDate:lt:2020-05-11T07::00::00.000Z.
  • Specify null values as null. For example, "all activities whose escalation date is null" is specified as ?filter=escalationDate:eq:null.

References to typekey fields automatically resolve to the field's code. For example, to filter on activities whose priority is set to urgent, use: GET /activities?filter=priority:eq:urgent.

You can also use the filter query for related resources added through the include parameter. For more information, see Query parameters for included resources.

Determining which fields you can filter on

For a given endpoint, there are several different ways to determine which fields you can filter on. The simplest is to run a query using a field you know to be invalid, such as GET ...?filter=dogsaregreat:eq:true. The resulting error message will provide a list of valid fields you can filter on, similar to this:

"message": "The field 'dogsaregreat' is not a filterable field for this endpoint. 
    The set of filterable fields is [accountNumber, accountStatus, createdDate]."

Another option that allows you to identify some of the attributes that are filterable is by reviewing the schema definition. If a field is filterable, then the schema definition includes the text: "filterable": true.

For example, the following is the schema description from Swagger UI for two fields returned by the Common API /activities endpoint.

escalated       boolean
                readOnly: true
                x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate  string($date-time)
                x-gw-nullable: true

Note that the escalated field includes the "filterable": true expression, but the escalationDate field does not. This means that you can filter on escalated, but not escalationDate.

The limitation to the preceding option is that it won't display custom filters. You might have to look at the Gosu resource files to determine whether a customization has been added to make a field filterable. See Cloud API Developer Guide for information on custom filters and where to find them.

Filtering on multiple values

You can include multiple filter criteria. To do this, each criteria requires its own filter expression. Separate the expressions with an ampersand (&). The syntax is:

filter=field:op:value&filter=field:op:value

When multiple criteria are specified, the criteria are ANDed together. Resources must meet all criteria to be included in the response. For example, the following GET returns only high priority activities that have not been escalated.

GET /activities?filter=priority:eq:high&filter=escalated:eq:false

The filter query parameter cannot be used to construct OR criteria.

When querying for a specific root resource, do not filter on the id property

When writing a call to GET a single root resource, use an endpoint that returns a single element, such as:

GET /activities/xc:20

Do not attempt to retrieve the resource by using an endpoint that returns a collection and filtering on the id property, as in:

GET /activities?filter=id:eq:xc::20

Typically, the latter approach does not work because collection endpoints do not have filterable id properties.

This restriction applies to the root resource only. There may be situations where you need to retrieve a root resource and one or more child resources. When retrieving the child resources, it may be possible and appropriate to filter on the child resource's id.

Filtering included resources

For information on how to use the filter parameter with included resources, see Query parameters for included resources.

Endpoints with default filters

Default filters

The following endpoints have default filters:

  • GET /admin/v1/users - By default, returns users only in the requester’s organization.
  • GET /account/v1/accounts/ - By default, it filters out accounts whose status is withdrawn.
  • GET /account/v1/accounts/{accountId}/jobs - By default, it filters out jobs that are not open.
  • GET /account/v1/accounts/{AccountId}/activities, GET /job/v1/jobs/{jobId}/activities, and GET /policy/v1/policies/{policyId}/activities - By default, they filter out activities that are not open.
  • GET /job/v1/jobs/{jobId}/uw-issues and GET /policy/v1/policies/{policyId}/uw-issues - By default, they filter out underwriting issues that are not active or where the blocking user is not the caller.
  • The LOB-specific GET /.../coverages endpoints - By default, they filter out coverages that are not selected.

Overriding default filters

You can use the filter query parameter to override default filters. There are several ways to do this.

  • You can retrieve unfiltered results by specifying filter=*none.
    • For example, GET /accounts/{AccountId}/jobs?filter=*none returns all jobs for the account, whether they are open or not.
  • You can override the default filter by specifying your own filter.
    • For example, GET /accounts/{AccountId}/jobs?filter=jobType:eq:Renewal returns all renewal jobs for the account, whether they are open or not.

If you want the response payload to reflect both the default filter and a custom filter, you must specify both filters explicitly.

Tutorial: Send a GET with the filter parameters

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  3. Specify Basic Auth authorization using user aapplegate and password gw.
  4. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities

  5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  6. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?filter=priority:eq:high

Checking your work

Compare the two payloads. Note that the first response payload includes all activities, whereas the second response payload contains only the activities with a high priority.