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')- 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).
- Before Targetprocess 3.13.2 in order to combine several rules you had to use logical grouping with brackets. Now the brackets are optional.
- 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 '\''Equality
Name eq 'My Name'
Not equality
Name ne 'My Name'
Greater than
Id gt 5
Greater than or equal
Project.Id gte 5
Less than
CreateDate lt '2011-10-01'
Less than or equal
TimeSpent lte 5.0
In list
Id in (155,156)
Not int list
not supported
Is true
IsActive eq 'true'
Is false
IsActive eq 'false'
Contains
Name contains 'rest'
Not contains
Tags not contains '*Major*'
Is set
Release is null
Is not set
Description is not null
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 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*')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]]]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=CreateDateIt 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