> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ConnectorFilter
> ConnectorFilter defines the document-routing rules applied to output connectors during sync orchestration
ConnectorFilter defines the document-routing rules applied to output connectors during sync orchestration. Each row is either a template filter (template=true, workspace=null โ a platform-managed default shared across all workspaces for a given connector type) or a custom filter (template=false, workspace scoped โ workspace-specific overrides). The `config` column carries a Hasura WHERE-clause JSONB predicate that gates which documents flow to the target connector, while `natural_language` provides a human-readable description for display in the workflow editor. ConnectorFilters are written exclusively by the seed pipeline (mikro:seed:connector-filters command and its migration equivalent) and surfaced read-only via the workspace-connectors JSON:API as a sideloaded included resource.
| Naming | Value |
| ------------------------------- | --------------------------------- |
| Object | ConnectorFilter |
| Resource type (JSON:API `type`) | `connector_filter` |
| Collection / records root | โ (not a records root) |
| REST base | `/v1/connector-filters` |
| Entity class | `ConnectorFilter` |
**Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
## API operations
| Operation | Method & path | Status |
| --------- | ----------------------------------- | ---------- |
| List | `GET /v1/connector-filters` | ๐ก Planned |
| Retrieve | `GET /v1/connector-filters/{id}` | ๐ก Planned |
| Create | `POST /v1/connector-filters` | ๐ก Planned |
| Update | `PATCH /v1/connector-filters/{id}` | ๐ก Planned |
| Delete | `DELETE /v1/connector-filters/{id}` | ๐ก Planned |
## Data model
### Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
| --------------------- | -------------------- | -------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| connector\_filter\_id | string (UUID) | โ
Yes | unique | Any valid UUID v4 | Public stable identifier for this filter. Generated by gen\_random\_uuid() on insert. Used as the JSON:API `id` field. |
| template | boolean | โ
Yes | default false | true \| false | Discriminator for filter kind. true = platform-managed template filter (workspace=null, shared across all workspaces for the connector type). false = workspace-specific custom filter. |
| config | object (JSONB) | โ
Yes | NOT NULL; no fixed schema โ shape is dynamic per connector | Any valid Hasura WHERE clause JSON object, e.g. \{ "document\_type": \{ "\_in": \["380", "381"] } } | Filter predicate expressed as a Hasura WHERE-clause JSONB object. Gates which documents are routed to the output connector during sync. Shape mirrors Hasura boolean expression syntax (field โ operator โ value). |
| natural\_language | string (text) | โ
Yes | NOT NULL; no length limit (text column) | Free text | Human-readable description of what the filter does. Displayed in the workflow editor as the suggested default rule copy for the output connector. |
| created\_at | ๐ system โ datetime | โ
Yes | timestamptz(6); NOT NULL | ISO 8601 UTC datetime | Timestamp set automatically on row creation via MikroORM onCreate hook. Never updated after insert. |
| updated\_at | ๐ system โ datetime | โช No | timestamptz(6); nullable | ISO 8601 UTC datetime or null | Timestamp refreshed automatically on every row update via MikroORM onUpdate hook. NULL until the first update. |
| deleted\_at | ๐ system โ datetime | โช No | timestamptz(6); nullable | ISO 8601 UTC datetime or null | Soft-delete timestamp. NULL means the filter is active. When set, the filter is excluded from all sync queries. Set by the seed pipeline on logical removal. |
### Relationships
| Name | Type | Required | Description |
| --------- | ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| connector | to-one (ManyToOne) | Yes โ NOT NULL FK | The Connector (provider definition) this filter is attached to. The connector FK is non-nullable and cascades on update. One connector may have at most one template filter (identity = connector\_pk + template=true + workspace=null + deleted\_at=null per seed idempotency contract) and any number of custom workspace filters. |
| workspace | to-one (ManyToOne, nullable) | No โ nullable FK (ON DELETE SET NULL) | The Workspace this custom filter belongs to. NULL for template filters (template=true). Set for workspace-specific custom filters (template=false). The FK cascades on update and sets null on workspace deletion. |
### System-computed
* connector\_filter\_id โ generated by gen\_random\_uuid() database default on INSERT; unique constraint ensures no collision
* created\_at โ set by MikroORM onCreate: () => new Date() hook; never modified after creation
* updated\_at โ set by both MikroORM onCreate and onUpdate hooks; reflects last modification time by the seed/migration pipeline
* deleted\_at โ soft-delete sentinel; set by the seed pipeline (syncConnectorFilters) when a filter is logically removed; never modified by user API calls
* Template filter identity โ the seed pipeline enforces a one-template-per-output-connector invariant: identity = (connector.pk, template=true, workspace=null, deleted\_at=null); subsequent seed runs update config and natural\_language in place rather than inserting duplicates
* Indexes โ idx\_connector\_filters\_workspace\_deleted (workspace, deleted\_at) for Hasura permission filter hot path; idx\_connector\_filters\_connector\_workspace (connector, workspace, template) for sync orchestration lookup; both created by Migration20260416000000\_hasura\_and\_service\_hot\_path\_indexes\_round4
## Example
```json theme={null}
{
"data": {
"type": "connector_filter",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"template": true,
"config": {
"document_type": {
"_in": ["380", "381", "383", "384", "325", "326", "385", "386"]
}
},
"natural_language": "Routes invoices, credit notes, and debit notes (UN/CEFACT document type codes 380, 381, 383, 384, 325, 326, 385, 386).",
"created_at": "2025-12-02T19:26:37.000Z",
"updated_at": "2026-04-14T16:00:00.000Z"
}
}
}
```
Source: `apps/api/src/database/entities/ConnectorFilter.ts` ยท domain: ingestion ยท tier: Infrastructure