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
- /v3/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 | 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. /v3/projects-expanded - Expanded Project Filtering
This endpoint supports the same filters as /v3/projects , but returns more detailed project information in the response.
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. /v2/assignments - Assignment Filtering
Available properties for filtering assignments:
| 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 |
task_active$eq:true |
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 |
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