Connector Filter (BETA)

When creating a Connect session, you can use the connector_filter parameter to control which connectors are available to the end user in the widget.

Structure

A connector_filter is an object containing a list of rules.

Rule

Field	Type	Description
action	"include" or "exclude"	Whether matching connectors should be included or excluded.
field	string	The connector attribute to match against. See Available Fields.
value	string or string[]	The value(s) to match. Use "*" to match all connectors.

Available Fields

Field	Type	Description
connector_id	string	The unique identifier of the connector (e.g. "esp:sabadell").
countries	string[]	Country codes the connector belongs to (e.g. ["esp", "fra"]).
type	string	The connector type (e.g. "e-banking", "psd2").

How Rules Are Applied

Rules are applied sequentially in the order they appear in the list. The starting set is all available connectors for your environment.

• An exclude rule removes matching connectors from the current set.
• An include rule adds matching connectors back from the full available set.

This sequential evaluation allows you to build precise filters by combining exclude and include rules.

Matching Behavior

• "*" as the value matches all connectors, can only be used in for connector_id field.
• For list fields: a rule matches if there is any overlap between the rule value and the connector's field value.
• For string fields: a rule matches if the values are equal.

Usage

Pass the connector_filter inside the configuration object when creating a session:

POST /v2/connect/sessions

{
  "configuration": {
    "connector_filter": {
      "rules": [
        { "action": "exclude", "field": "connector_id", "value": "*" },
        { "action": "include", "field": "countries", "value": ["spain"] }
      ]
    },
    ... # other configuration parameters
  }
}

When connector_filter is not provided, all connectors available for your environment are shown.

Examples

Show only specific connectors

Exclude everything, then include only the connectors you want:

{
  "connector_filter": {
    "rules": [
      { "action": "exclude", "field": "connector_id", "value": "*" },
      { "action": "include", "field": "connector_id", "value": ["esp:sabadell", "esp:caixa"] }
    ]
  }
}

Show only PSD2 connectors

Exclude everything, then include only the PSD2 type:

{
  "connector_filter": {
    "rules": [
      { "action": "exclude", "field": "connector_id", "value": "*" },
      { "action": "include", "field": "type", "value": "psd2" }
    ]
  }
}

Combine multiple criteria

Exclude everything, include Spanish and French connectors, then remove e-banking types from that set. The result is all non-e-banking connectors from Spain and France:

{
  "connector_filter": {
    "rules": [
      { "action": "exclude", "field": "connector_id", "value": "*" },
      { "action": "include", "field": "countries", "value": ["spain", "france"] },
      { "action": "exclude", "field": "type", "value": "e-banking" }
    ]
  }
}

Rules are applied in order, so the sequence matters. The include adds Spanish and French connectors to the (empty) set, then the exclude removes e-banking ones from that set.

API Reference

Preview Connector Filter

Preview which connectors would be available for a given connector_filter. Use this endpoint to test and validate your filter rules before creating a session.

https://api.flanks.io/connect/v2/connectors/preview-connector-filter

Headers

Header	Value
Authorization	Bearer <access_token> (See Authentication).
Content-Type	application/json

Body (JSON encoded)

Parameter	Type	Description
connector_filter*	object	The ConnectorFilter object
page_token	string	If provided, the request will fetch the next page for this query

(*) Mandatory Parameters

ConnectorFilter Object

Field	Type	Description
rules *	[Rule]	A list of rules to apply

Example Request

{
  "connector_filter": {
    "rules": [
      { "action": "exclude", "field": "connector_id", "value": "*" },
      { "action": "include", "field": "countries", "value": ["spain"] }
    ]
  }
}

Responses

200 OK

  {
    "items": [{ [Connector](#connector-model) }],
    "next_page_token": string | null,
  }

Returns a paginated result, where items will be a list of Connectors.

400 Validation Error

{
    "success": false,
    "error": {
        "code": "ValidationError",
        "details": [
            { "error_type": string, "field": string },
            ...
        ],
    },
    "trace_id": string,
}

Some fields are missing or incorrect.

401 Invalid Credentials

{
    "error": "Invalid credentials"
}

The Authorization header is either empty or contains an invalid or expired access_token.

500 Internal Error

{
    "error": "Internal Error"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Connector Model

{
  "countries": [string],
  "id": string,
  "name": string,
  "type": string,  
}

Notes

• The connector_filter cannot be used together with connector_id or connection_id in the session configuration.