Passthrough Filters

Passthrough Filters allow you to directly pass key-value pairs into the underlying app’s API request during syncs.
They are useful when you want to leverage the app’s native filtering capabilities to narrow down the data fetched from the source itself.

Unlike Native Filters, Knit does not validate Passthrough Filters — it simply forwards them to the app’s API.
It is your responsibility to refer to the respective app's API documentation and ensure you are using correct filter keys and values.

Use Case

Passthrough Filters are ideal when you need to:

• Apply filters that are specific to the app and not standardized by Knit.
• Fine-tune the API requests with custom query parameters, request body values, or headers based on app-specific features.

Filter Format

Passthrough filters are passed inside a passThroughFilters object, structured as follows:

 {
  "query": {
    "key1": "value1",
    "key2": "value2"
  },
  "body": {
    "key3": "value3"
  },
  "headers": {
    "key4": "value4"
  }
}

• query: These key-value pairs are added to the query string of the API request.
• body: These key-value pairs are added to the body of the API request (if applicable).
• headersThese key-value pairs are added to the headers of the API request.

📘

Note:

If the API expects multiple values for a field (e.g., multiple statuses), you can pass them as a comma-separated string.
Example: "status": "draft,published"

Example: Filtering by Status and Department

Suppose you want to fetch records where the status is draft and the department_id is 4012058007, your passthrough filter would look like:

 {
  "query": {
    "status": "draft",
    "department_id": "4012058007"
  }
}

If you want to pass body parameters as well:

 {
  "query": {
    "status": "draft",
    "department_id": "4012058007"
  },
  "body": {
    "key": "value"
  }
}

Important Guidelines

• Always refer to the specific app's API documentation to determine the supported keys and expected values.
• Knit will pass the filters as provided without modifying or validating them.
• Incorrect or invalid filters may lead to errors or empty responses.
• When passing multiple values for a field, separate them with commas if the API expects it.

To add Passthrough Filters to your integration, use the Update Sync Filter API and provide the filter JSON.

📘

Note:

Updating the filter will trigger an initial_sync to rebaseline the data with the new filter.
You can control this behavior using the triggerSync parameter in the API request.

Once the filter is set, all future delta_syncs for that integration will track only the data points that pass the filters, helping you fetch more targeted data from your syncs.

Sample cURL Request

curl --location 'https://api.getknit.dev/v1.0/sync.filter.update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--data '{
    "dataType" : "ats_applications",
    "passThroughFilters": {
        "query": {
            "status": "draft",
            "department_id": "4012058007"
        }
    }
}'

By using Passthrough Filters correctly, you can optimize your syncs and fetch only the data you truly need based on the app’s supported capabilities.