API Advanced Filtering
The eHour API provides filtering capabilities to help you pinpoint the data you need. This article explains how to use the filter parameter on API endpoints that support filtering.
Supported Endpoints
The following endpoints support advanced filtering:
- /v2/clients
- /v2/clients-expanded
- /v3/projects
- /v4/projects-expanded
- /v3/users
- /v2/teams
- /v2/assignments
Basic Filter Structure
A filter consists of a property name, an operator, and a value to filter on. The format is:
property_name$operator:value
Available Operators
Comparison Operators
The following cooperators can be used:
| Operator | Description | Example |
|---|---|---|
$eq |
Equal to | client_name$eq:Acme |
$ne |
Not equal to | client_name$ne:Acme |
$like |
Contains or matches pattern (use * as wildcards) | client_name$like:*Acme* |
$in |
Matches any value in a comma-separated list. Supports null to match unset/NULL properties. | client_id$in:CLT1,CLT2,CLT3 |
$contains |
Array contains the given value | user_id$contains:USR1 |
$before |
Date is before the given date | client_created$before:2023-01-01 |
$after |
Date is after the given date | client_created$after:2022-01-01 |
Logical Operators
You can combine multiple filters using logical operators. The syntax for logical operators is:
client_active$eq:true$and:client_name$like:*Acme*
| Operator | Description | Example |
|---|---|---|
$and |
All conditions must be true | client_active$eq:true$and:client_name$like:*Acme* |
$or |
Any condition can be true | client_name$like:*Acme*$or:client_name$like:*Corp* |
Parantheses
You can also use parentheses for more complex combined logic. For example, to * find all inactive clients, or have "Tech" in their name created before March 18, 2025:
client_created$before:2025-03-18$and:(client_name$like:tech*$or:client_active$eq:false)
API Endpoints and Supported Fields
1. /v2/clients - Client Filtering
Available properties for filtering clients:
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
client_id |
String | $eq , $ne , $in |
client_id$eq:CUS42 |
client_active |
Boolean | $eq , $ne |
client_active$eq:true |
client_name |
String | $eq , $ne , $like |
client_name$like:*Tech* |
client_code |
String | $eq , $ne , $like |
client_code$eq:TECH01 |
client_created |
Date | $eq , $before , $after |
client_created$after:2023-01-01 |
client_description |
String | $eq , $ne , $like |
client_description$like:*services* |
2. /v2/clients-expanded - Expanded Client Filtering
This endpoint supports the same filters as /v2/clients , but returns more detailed client information in the response.
3. /v3/projects - Project Filtering
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
project_id |
String | $eq , $ne , $in |
project_id$eq:PRJ42 |
project_active |
Boolean | $eq , $ne |
project_active$eq:true |
project_name |
String | $eq , $ne , $like , $in |
project_name$like:Web* |
project_code |
String | $eq , $ne , $like , $in |
project_code$eq:DEV2023 |
project_created |
Date | $eq , $ne , $before , $after |
project_created$after:2023-01-01 |
client_id |
String | $eq , $ne , $in |
client_id$in:CLT12,CLT13,CLT14 |
client_name |
String | $eq , $ne , $like , $in |
client_name$eq:ACME |
client_code |
String | $eq , $ne , $like , $in |
client_code$like:COR* |
client_created |
Date | $eq , $ne , $before , $after |
client_created$before:2024-01-01 |
4. /v4/projects-expanded - Expanded Project Filtering
This endpoint supports the same filters as /v3/projects , but returns more detailed project information in the response. The following property can also be used:
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
project_manager_active |
Boolean | $eq , $ne , $in |
project_manager_active$eq:true |
Example
Inactive projects with an active project manager, or no project manager:
project_active$eq:false$and:project_manager_active$in:true,null
5. /v3/users - Users Filtering
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
user_id |
String | $eq , $ne , $in |
user_id$eq:USR42 |
user_active |
Boolean | $eq , $ne |
user_active$eq:true |
user_name |
String | $eq , $ne , $like , $in |
user_name$like:John* |
user_email |
String | $eq , $ne , $like , $in |
user_email$in:john@example.com,jane@example.com |
user_created |
Date | $eq , $ne , $before , $after |
user_created$after:2023-01-01 |
6. /v2/teams Team Filtering
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
team_id |
String | $eq , $ne , $in |
team_id$eq:TEM42 |
team_active |
Boolean | $eq , $ne |
team_active$eq:true |
team_name |
String | $eq , $ne , $like , $in |
team_name$like:*evelopmen* |
team_code |
String | $eq , $ne , $like , $in |
team_code$ne:DEV01 |
team_created |
Date | $eq , $ne , $before , $after |
team_created$after:2025-01-01$and:team_created$before:2025-02-01 |
7. /v3/assignments - Assignment Filtering
Available properties for filtering assignments:
Important: The properties task_active and team_assignment_active can be null when no task or team assignment exists. To match both active and NULL values, use the $in operator with null: task_active$in:true,null
| Property | Data Type | Supported Operators | Example |
|---|---|---|---|
active |
Boolean | $eq , $ne |
active$eq:true |
user_active |
Boolean | $eq , $ne |
user_active$eq:true |
project_active |
Boolean | $eq , $ne |
project_active$eq:true |
client_active |
Boolean | $eq , $ne |
client_active$eq:true |
task_active |
Boolean | $eq , $ne , $in |
task_active$eq:true task_active$in:true,null |
active_period |
Date Range | $eq , $before , $after |
active_period$eq:2023-01-01 |
project_id |
Number | $eq , $ne , $in |
project_id$in:1,2,3 |
client_id |
Number | $eq , $ne , $in |
client_id$eq:5 |
user_id |
String | $eq , $ne , $in |
user_id$eq:USR1 |
task_id |
Number | $eq , $ne , $in |
task_id$eq:10 |
team_id |
Number | $eq , $ne , $in |
team_id$eq:3 |
project_name |
String | $eq , $ne , $like |
project_name$like:*Website* |
client_name |
String | $eq , $ne , $like |
client_name$eq:Acme |
user_name |
String | $eq , $ne , $like |
user_name$like:*Smith* |
task_name |
String | $eq , $ne , $like |
task_name$like:*Development* |
team_name |
String | $eq , $ne , $like |
team_name$eq:Engineering |
project_code |
String | $eq , $ne , $like |
project_code$eq:PRJ01 |
client_code |
String | $eq , $ne , $like |
client_code$like:ACM* |
team_code |
String | $eq , $ne , $like |
team_code$eq:ENG |
user_email |
String | $eq , $ne , $like |
user_email$like:*@example.com |
user_created |
Date | $eq , $before , $after |
user_created$after:2023-01-01 |
project_created |
Date | $eq , $before , $after |
project_created$before:2023-12-31 |
client_created |
Date | $eq , $before , $after |
client_created$after:2023-01-01 |
task_created |
Date | $eq , $before , $after |
task_created$before:2023-12-31 |
team_created |
Date | $eq , $before , $after |
team_created$after:2023-01-01 |
team_assignment_active |
Boolean | $eq , $ne , $in |
team_assignment_active$eq:true team_assignment_active$in:true,null |
Migrating from v1
The v1 endpoint GET /api/v1/assignments?state=active&resource-state=active returns assignments that are:
- Active with active users, projects, and clients
- Include assignments WITHOUT tasks (task_active = null) OR with active tasks
- Include assignments WITHOUT team assignments (team_assignment_active = null) OR with active team assignments
v1 Query:
GET /api/v1/assignments?state=active&resource-state=active
v3 Equivalent:
GET /api/v3/assignments?filter=active$eq:true$and:user_active$eq:true$and:project_active$eq:true$and:client_active$eq:true$and:task_active$in:true,null$and:team_assignment_active$in:true,null
Notes on Field Names
- You can use both formats for field names:
- With underscores:
client_name,project_id - Without underscores:
clientname,projectid
- With underscores:
- Both formats will work the same way in your filter queries
Tips for Effective Filtering
- For string comparisons, operators are case-insensitive
- Use wildcards (*) with the $like operator for partial matches
- Date filters work with ISO format dates (YYYY-MM-DD) or YYYY-MM-dd'T'HH:mm:ss