Mapping Filters - Feature Overview
Mapping Filters provide a powerful, CRM-agnostic way to filter records during data synchronization. Mapping Filters work consistently across all supported CRMs for both bulk exports and events.
Mapping Filter Benefits:
Unlike the where query parameter (which only works fully with Salesforce), Mapping Filters work consistently across all supported CRMs and are applied to both Bulk exports and Events.
- Universal CRM Support: Works identically across all supported CRMs (Salesforce, HubSpot, Dynamics, Zoho, Netsuite, Pipedrive, Monday, Veeva Vault, Sugar, Insightly...)
- Works for Bulks & Events: Same filter configuration applies to both bulk data exports and real-time event syncing
- Rich Query Language: MongoDB-style operators for flexible filtering logic
- Type-Aware Comparisons: Automatically handles string/number coercion and date comparisons
- Nested Field Support: Filter on deeply nested fields using dot notation
How It Works:
Filters are configured on your Mapping and define which records should be excluded from the results. Records matching the filter criteria are filtered out; records that don't match are included in your data.
For Events: filtered records are automatically reported in the deleted_records array of the webhook payload, allowing your system to track exclusions.
Supported Operators:
Comparison Operators:
List Operators:
String Operators:
Existence Operators:
Logical Operators:
Examples:
Example 1: Exclude inactive records
{
"filters": {
"status": "inactive"
}
}Records with status = "inactive" will be excluded
Example 2: Exclude low-value opportunities
{
"filters": {
"amount": {"$lt": 1000}
}
}Records with amount < 1000 will be excluded
Example 3: Exclude records based on mulitple criteria
{
"filters": {
"$or": [
{"status": "closed"},
{"amount": {"$lt": 500}}
]
}
}Records that are closed OR have amount < 500 will be excluded
Example 4: Filter by date range
{
"filters": {
"created_at": {"$lt": "2024-01-01T00:00:00Z"}
}
}Records created before 2024 will be excluded
Example 5: Complex multi-condition filter
{
"filters": {
"$and": [
{"status": {"$in": ["test", "demo", "internal"]}},
{"owner_email": {"$contains": "@internal.com"}}
]
}
}Records that are test/demo/internal AND owned by internal users will be excluded
Example 6: Filter on nested fields
{
"filters": {
"address.country": {"$ne": "US"}
}
}Records where address.country is not "US" will be excluded-----Configuration
Filters are set on the Mapping object via the filters property:
{
"company_id": "your-company-id",
"badger_object_name": "leads",
"crm_object_name": "Lead",
"fields": [...],
"filters": {
"status": {"$in": ["junk", "disqualified"]}
},
"record_id_field": "Id"
}Note: Setting record_id_field is mandatory when using filters, as it is necessary for filtered records to be properly identified in event payloads.
Best Practices:
- Use filters instead of where for cross-CRM compatibility
- Set record_id_field to track which records were filtered in event webhooks
- Test filters with a small bulk export before applying to production events
- Use $and/$or for complex logic rather than relying on implicit AND behavior
- Leverage date comparisons for time-based filtering (ISO 8601 format supported)
Summary: where vs. filters
Recommendation: Use Mapping Filters for consistent behavior across all CRMs and both Bulks and Events.
