Sorting and Filters

Filtering

REST API supports filtering by fields and nested fields. To set a requested filter use where=condition query parameter. For example, this request will return all bugs in a "In Progress" state:

/api/v1/Bugs?where=EntityState.Name eq 'In Progress'

You can combine several filtering conditions using operator and:

/api/v1/Bugs?where=(CreateDate gt '2011-01-01')and(EndDate lt '2011-02-01')

🚧

1. Before Targetprocess 3.13.2 the operator 'and' was case-sensitive, so it had to be in lower case (e.g. 'AND' or 'And' were not working).
2. Before Targetprocess 3.13.2 in order to combine several rules you had to use logical grouping with brackets. Now the brackets are optional.
3. The operator 'or' is not supported. Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/53623

Escaping of single quote symbol in values can be done using preceding backslash:

/api/v1/Userstories?where=Name contains '\''

Available operators

Filtering by Custom Field values

It is possible to filter out entities by their Custom Field values. You must provide field name in your query. Format is the following: ?where=CustomFields.FieldName eq 'Value'. For example:

/api/v1/Bugs?where=(CustomFields.Browser eq 'Firefox')

When field name contains space, additional quotes should be added into query:

/api/v1/UserStories?where=('CustomFields.Release Notes' is not null)

❗️

Filtering by values in Calculated Custom Fields is not supported within REST API.

Filtering by Tags

Filtering by Tags is possible. Here is how to filter User Stories with tag abc assigned:

/api/v1/userstories?where=(Tags contains 'abc')

When a tag has two words in between, the value should be placed into additional double quotes. Here is how to filter User Stories with tag two words assigned:

/api/v1/userstories?where=(Tags contains "'two words'")

Wildcards are supported. Asterisk * symbol means there are zero or any number or symbols instead of it. Asterisks can be appended to the beginning or the end of search string, but not into the middle part.

For example, tag abcdef matches wildcard *abc*:

/api/v1/userstories?where=(Tags contains '*abc*')

Filtering in nested collections

It is not possible to filter out entities by some attributes of their collections in REST APIv1.
Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/146598

Sometimes you can work around this limitation by querying the collections directly, for example:

api/v1/Assignments?
where=(GeneralUser.Id eq 1234)and(Assignable.EntityType.Name eq 'UserStory')&
include=[Assignable[Id,Name]]

/api/v1/Relations?
include=[Master[EntityType[Name]],Slave[EntityType[Name]]]&
where=(Master.EntityType.Name eq 'Request')and(Slave.EntityType.Name eq 'Bug')

🚧

With Multiple Teams feature the "Team" field of Assignable API resource became deprecated, so now working with Teams means working with "TeamAssignment" collection.

/api/v1/TeamAssignments?
where=(Team.ID eq 1234)and(Assignable.EntityType.Name eq 'UserStory')&
include=[Assignable[ID,Name,AssignedTeams[Team,StartDate,EndDate]]]

/api/v1/TeamAssignments?
where=(Team.Name eq 'Alpha')and(Assignable.EntityType.Name eq 'Feature')&
include=[Assignable[ID,Name,AssignedTeams[Team,StartDate,EndDate]]]

Sorting

You can order the REST API results using any field (simple or nested). Use orderby=field or orderbydesc=field to sort data ascending or descending. For example, this request will return all bugs ordered by creation date (recent bugs on top):

/api/v1/Bugs?orderByDesc=CreateDate

🚧

It is not possible to sort by more than one criteria.
Here is an idea to support it in the future: https://servicedesk.targetprocess.com/request/145911