Skip to main content
The API uses Spatie Query Builder v6 for filtering results. This provides a flexible way to filter collections based on URL parameters.

​
Basic Filtering

Use the filter query parameter with the field name: 
# Filter companies by name
curl https://api.paystub.dev/companies?filter[name]=Acme

# Filter employees by email
curl https://api.paystub.dev/employees?filter[email][email protected]

​
Available Filter Types

​
Exact Match

# Exact match filtering
curl https://api.paystub.dev/documents?filter[status]=completed

​
Partial Match

# Partial text match (case-insensitive)
curl https://api.paystub.dev/companies?filter[name]=acme

​
Multiple Values

# Filter by multiple status values
curl https://api.paystub.dev/documents?filter[status]=pending,processing

​
Relations

# Filter employees by company name
curl https://api.paystub.dev/employees?filter[company.name]=Acme

​
Filter Operations

The API supports various filter operations:
OperationDescriptionExample
equalsExact matchfilter[status]=active
containsPartial matchfilter[name]=acme
gtGreater thanfilter[amount.gt]=1000
gteGreater than or equalfilter[amount.gte]=1000
ltLess thanfilter[amount.lt]=1000
lteLess than or equalfilter[amount.lte]=1000

​
Filtering by Date

Use ISO 8601 format for date filtering: 
# Get documents created after a specific date
curl https://api.paystub.dev/documents?filter[created_at.gt]=2024-01-01T00:00:00Z

​
Combining Filters

Multiple filters can be combined: 
curl https://api.paystub.dev/employees?\
filter[company_id]=1\
&filter[status]=active\
&filter[created_at.gt]=2024-01-01T00:00:00Z

​
Best Practices

  1. Use appropriate filter types for better performance
  2. Combine filters to narrow down results
  3. Consider pagination when filtering large datasets
  4. Validate filter values on the client side
  5. Handle empty result sets gracefully

​
Filterable Fields

​
Companies

  • name
  • email
  • status
  • created_at

​
Employees

  • company_id
  • first_name
  • last_name
  • email
  • status
  • created_at

​
Documents

  • uuid
  • type
  • status
  • company_id
  • employee_id
  • created_at

​
Error Handling

Invalid filters will return a 422 error: 
{
  "success": false,
  "message": "Invalid filter parameters",
  "errors": {
    "filter.status": ["Invalid status value provided"]
  }
}