Filter Rules

Overview

The Tabs API provides a powerful filtering system that allows you to query and filter data across all endpoints using consistent syntax and rules. This guide covers how to construct and use filters effectively.

Filter Syntax

Filters use a structured format: property:rule:"value"

Basic Structure

GET /v3/customers?filter=name:eq:"Acme Corp"

Multiple Filters

Use commas to separate multiple filters (all filters are combined with AND logic):

GET /v3/invoices?filter=status:eq:"PENDING",customerId:eq:"123e4567-e89b"

Handling Commas in Values

Use double quotes to wrap values containing commas:

GET /v3/customers?filter=name:like:"Acme, Corp"

Filter Rules

The following filter rules are supported:

Rule	Operator	Description	Example
`eq`	equals	Exact match	`status:eq:"ACTIVE"`
`neq`	not equals	Not equal to	`status:neq:"DELETED"`
`gt`	greater than	Greater than	`total:gt:"100"`
`gte`	greater than or equals	Greater than or equal	`total:gte:"100"`
`lt`	less than	Less than	`total:lt:"1000"`
`lte`	less than or equals	Less than or equal	`total:lte:"1000"`
`like`	contains	Case-insensitive substring match	`name:like:"acme"`
`nlike`	not like	Does not contain substring	`name:nlike:"test"`
`in`	in array	Value is in list (use \| separator)	`status:in:"ACTIVE\
`nin`	not in array	Value is not in list	`status:nin:"DELETED\
`isnull`	is null	Field is null	`endDate:isnull:""`
`isnotnull`	is not null	Field is not null	`endDate:isnotnull:""`

Pagination

All filtered endpoints support pagination with these query parameters:

page - Page number (default: 1)
limit - Items per page (default: 50)

GET /v3/customers?filter=name:like:"corp"&page=2&limit=25

Nested Property Filtering

Some properties support nested filtering using dot notation:

GET /v3/customers?filter=externalIds.externalId:eq:"EXT123"

This filters customers where any of their external IDs matches "EXT123".

Date Filtering

When filtering by dates, use ISO format (YYYY-MM-DD):

GET /events?filter=datetime:gte:"2024-01-01",datetime:lt:"2024-02-01"

Common Examples

Find active customers with "Corp" in name

GET /v3/customers?filter=name:like:"Corp"

Get pending invoices over $500

GET /v3/invoices?filter=status:eq:"PENDING",total:gt:"500"

Find payments received this month

GET /v3/payments?filter=receivedAt:gte:"2024-01-01",receivedAt:lt:"2024-02-01"

Get contracts by multiple statuses

GET /v3/contracts?filter=status:in:"ACTIVE|PENDING"

Find customers without external IDs

GET /v3/customers?filter=externalIds.externalId:isnull:""

Error Handling

The API will return 400 Bad Request for:

Invalid filter format
Unsupported properties for the endpoint
Invalid filter rules
Malformed filter syntax

Response Format

All filtered endpoints return paginated responses:

{
  "success": true,
  "payload": {
    "data": [...],
    "currentPage": 1,
    "limit": 50,
    "totalItems": 150
  }
}

Best Practices

Use specific filters - More specific filters improve performance
Combine filters efficiently - Use multiple filters to narrow results
Handle pagination - Always implement pagination for large datasets
Quote values properly - Use double quotes for values with special characters
Test filter combinations - Verify your filter logic returns expected results
Collapse