Filtering

By default, the Gtmhub REST APIs work with all objects of the corresponding type. Very often you want to retrieve a collection of items based on some criteria. For example, all Objectives from a specific session. In such cases you use filtering. The Gtmhub REST API endpoints support filtering by selected properties of the object. To filter your request, pass the desired property name as a URL query parameter, and set the desired value to filter by.

When an endpoint supports filtering, the fields you can filter by will be specified in the endpoint documentation.

Example:
To get all objectives, whose attainment is greater than 0.5 make use:
https://app.(us.)gtmhub.com/api/v1/goals?attainment=>0.5

Gtmhub API V2 - In V2 you can use the filter query parameter. The value given to this query parameter should be a Mongo syntax valid filter. This section shows examples of the specific filter syntax for the most common use cases.

Filtering by ID

Gtmhub API V2 does not have endpoints fro getting a single item by its ID. To get a specific item by its unique identifier, you must add a filter contianig the item ID.

Example:
To get an objective by its ID, use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={_id:"6066c77f24f5f700014b39a3"}

When you filter by “id” you need to add an underscore(_) at the beginning

Filtering by a property of the object

Each Objective has a sessionId property which indicates the session it belongs to. To get the Objectives from a specific session use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={sessionId:”6065d3f8245fsa92402”}

Filtering by multiple values

Following the above example, to get the Objectives from two or more sessions use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={sessionId:{$in:[”6065d3f8245fsa92402”, “6065d3f8245fsa92402”]}}

Filtering by string match (e.g. RegEx)

  • To get the objectives, whose names begin with “Gtmhub” use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={name:{$regex: “^Gtmhub”}}
  • To get the objectives, whose names end with “Gtmhub” use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={name:{$regex: “Gtmhub$”}}

Combining filters (AND logical operator)

You can combine multiple filter criteria. Just start your filter with an and operator and then list the filters to be included:

Example:
To get the objectives with a specific name and from a specific session use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={$and:[{sessionId:"6065d3f824f5f70001e18222"},{name:"Gtmhub"}]}

Combining filters (AND logical operator)

Similar to the previous example, to filter by an or logical operator, start your filter with it and then list all filters that should be considered.

Example:
To get the objectives where a user is either the owner or the assignee use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={$or:[{ownerId:"6065c702b97d1200017306b0"},{assignee._id:"6065c702b97d1200017306b0"}]}

Filtering by numeric value

You can filter by numeric properties using the eq(equals), gt(greater than), lt(lower than), gte(greater than or equals), ... , operators.

Example:

  • To get the objectives, whose attainment is greater than or equal to 0.5 use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={attainment:{$gte:0.5}}
  • To get the objectives, whose attainment is greater than 0.5 use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={attainment:{$gt:0.5}}
  • To get the objectives, whose attainment is lower than 0.5 use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={attainment:{$lt:0.5}}
  • To get the objectives, whose attainment is lower than 0.7 and it’s greater than 0.5 use:
    https://app.(us.)gtmhub.com/api/v2/goals?filter={$and:[{attainment:{$lt:0.7}},{attainment:{$gt:0.5}}]}

Filtering by dates

Date filtering is not too different that numeric filters. Pass the comparison operator and then the date value in ISO format.

Example:
To get The objectives, that are created on or before a specific date use:
https://app.(us.)gtmhub.com/api/v2/goals?filter={dateCreated:{$lte:"2021-05-01T14:16:08.669Z"}}

Filtering by user roles

Filter a list of users by a role (or several roles) is a bit of a special case in terms of its sytax. Since the user roles are stored as an array of role objects you must use the mongoDb elemMatch operator.

Example:
To get all users who have the admin role use:
https://app.gtmhub.com/api/v2/users?filter={"roles":{"$elemMatch":{"name":{"$in":["admin"]}}}} if you want to match by the role name or
https://app.gtmhub.com/api/v2/users?filter={"roles":{"$elemMatch":{"_id":{"$in":["573d93d9ed915d00052efb6b"]}}}} if you want to match the role by its Id

To get a list of users who are assigned to either admin or data roles you can extend the query like this:
https://app.gtmhub.com/api/v2/users?filter={"roles":{"$elemMatch":{"_id":{"$in":["573d93d9ed915d00052efb6b","5d9703be1e3972000175852f"]}}}}