Filtering
The ServiceM8 REST API supports OData-style filtering through the $filter
query parameter. This allows you to retrieve specific subsets of resources based on field values and conditions.
Basic Filter Syntax
Single Condition
GET /api_1.0/{resource}.json?$filter={field} {operator} {value}
Examples
# Get all active jobs
GET /api_1.0/job.json?$filter=active eq 1
# Get jobs with a specific status
GET /api_1.0/job.json?$filter=status eq 'Work Order'
# Get companies created after a specific date
GET /api_1.0/company.json?$filter=create_date gt '2023-01-01'
Supported Operators
Operator | Description | Example |
---|---|---|
eq | Equal to | status eq 'Quote' |
ne | Not equal to | status ne 'Completed' |
gt | Greater than | total_price gt 1000 |
lt | Less than | total_price lt 5000 |
Note: Greater than or equal (ge
) and less than or equal (le
) operators are not currently supported.
Multiple Conditions with AND
Multiple filter conditions can be combined using the and
operator. The API supports up to 10 conditions in a single request.
Syntax
$filter={condition1} and {condition2} and {condition3}
Examples
# Jobs with status 'Work Order' AND active
GET /api_1.0/job.json?$filter=status eq 'Work Order' and active eq 1
# Jobs with high value AND specific company
GET /api_1.0/job.json?$filter=total_price gt 1000 and company_uuid eq '550e8400-e29b-41d4-a716-446655440000'
# Complex filter with multiple conditions
GET /api_1.0/job.json?$filter=status eq 'Work Order' and active eq 1 and total_price gt 500 and total_price lt 5000
Limitations
- Maximum of 10 conditions per request
- Only
and
operator is supported (noor
ornot
) - No support for parentheses/grouping
If you need more complex filtering:
- Break your query into multiple API requests
- Use the results from one request to filter subsequent requests
- Consider using webhooks or batch processing for complex data operations
Value Formatting
String Values
String values must be enclosed in single quotes:
$filter=name eq 'John Smith'
$filter=status eq 'Work Order'
Numeric Values
Numeric values should not be quoted:
$filter=active eq 1
$filter=total_price gt 1000.50
Special Characters in Strings
Spaces and special characters within string values are supported:
$filter=name eq 'Smith & Sons Plumbing'
$filter=address eq '123 Main St, Suite 100'
Field Value Limitations
- Maximum length of any filter value: 255 characters
- Field names must be valid API fields for the resource type
- Field names are case-sensitive
Error Handling
Common Errors
Invalid Filter Format
{
"errorCode": 400,
"message": "Invalid Record Filter Specified"
}
Too Many Conditions
{
"errorCode": 400,
"message": "Maximum of 10 filter conditions allowed. Please reduce the number of conditions or use multiple requests."
}
Unsupported Operators
{
"errorCode": 400,
"message": "OR and NOT operators are not supported. Use multiple requests or contact support."
}
Invalid Field Name
{
"errorCode": 400,
"message": "Invalid Record Filter Field Specified"
}
Value Too Long
{
"errorCode": 400,
"message": "Record Filter Value is too long"
}
URL Encoding
Remember to properly URL encode filter expressions:
# Unencoded (for readability)
GET /api_1.0/job.json?$filter=status eq 'Work Order' and active eq 1
# URL encoded (actual request)
GET /api_1.0/job.json?%24filter=status%20eq%20%27Work%20Order%27%20and%20active%20eq%201
Working Examples with cURL
Single Condition
# Get all active jobs
curl -X GET "https://api.servicem8.com/api_1.0/job.json?%24filter=active%20eq%201" \
-H "X-API-Key: YOUR_API_KEY"
Multiple Conditions
# Get active work orders over $1000
curl -X GET "https://api.servicem8.com/api_1.0/job.json?%24filter=status%20eq%20%27Work%20Order%27%20and%20active%20eq%201%20and%20total_price%20gt%201000" \
-H "X-API-Key: YOUR_API_KEY"
Complex Business Query
# Get incomplete high-value jobs for a specific company
curl -X GET "https://api.servicem8.com/api_1.0/job.json?%24filter=company_uuid%20eq%20%27550e8400-e29b-41d4-a716-446655440000%27%20and%20status%20ne%20%27Completed%27%20and%20total_price%20gt%202000%20and%20active%20eq%201" \
-H "X-API-Key: YOUR_API_KEY"
Combining with Other Parameters
Filters work alongside other API parameters:
# Filter with sorting
GET /api_1.0/job.json?$filter=status eq 'Work Order'&$sort=due_date desc
# Filter with cursor-based pagination
GET /api_1.0/job.json?$filter=active eq 1&cursor=-1
Performance Best Practices
- Use Indexed Fields: Filter on fields like
uuid
,active
, andstatus
for best performance - Be Specific: More conditions generally mean smaller, faster result sets
- Avoid Complex Logic: If you need OR conditions, make separate requests
- Cache When Possible: Cache filtered results that don't change frequently
- Consider Pagination: Use cursor-based pagination for large result sets
Related Documentation
Updated 1 day ago