API reference

Financial Connections

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

List Accounts

GET/v1/financial_connections/accounts

Returns a list of Financial Connections Account objects.

Query parameters

  • account_holderobject

    If present, only return accounts that belong to the specified account holder. account_holder[customer] and account_holder[account] are mutually exclusive.

    Show 3 child parameters
    • accountstring
    • customerstring
    • customer_accountstring
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • sessionstring

    If present, only return accounts that were collected as part of the given session.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of financial_connections.account objects.

GET /v1/financial_connections/accounts
curl -G https://api.knoxapi.com/v1/financial_connections/accounts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/financial_connections/accounts",
  "has_more": false,
  "data": [
    {
      "account_holder": {
        "customer": "cus_QXg1o8vcGmoR32",
        "type": "customer"
      },
      "balance": {
        "as_of": 93102340,
        "current": {
          "undefined": 1126940025
        },
        "type": "cash"
      },
      "balance_refresh": {
        "last_attempted_at": 1981828143,
        "next_refresh_available_at": null,
        "status": "failed"
      },
      "category": "cash",
      "created": 1234567890,
      "display_name": "Sample Checking Account",
      "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
      "institution_name": "StripeBank",
      "last4": "6789",
      "livemode": false,
      "object": "financial_connections.account",
      "ownership": null,
      "ownership_refresh": {
        "last_attempted_at": 1981828143,
        "next_refresh_available_at": null,
        "status": "failed"
      },
      "permissions": [],
      "status": "active",
      "subcategory": "checking",
      "subscriptions": [],
      "supported_payment_method_types": [
        "us_bank_account"
      ],
      "transaction_refresh": {
        "id": "obj_123",
        "last_attempted_at": 1981828143,
        "next_refresh_available_at": null,
        "status": "failed"
      },
      "account_numbers": null
    }
  ]
}

Create a Session

POST/v1/financial_connections/sessions

To launch the Financial Connections authorization flow, create a Session. The session’s client_secret can be used to launch the flow using Stripe.js.

Body parameters

  • account_holderobjectRequired

    The account holder to link accounts for.

    Show 4 child parameters
    • typestringRequired
      Possible values
      • account
      • customer
    • accountstring
    • customerstring
    • customer_accountstring
  • permissionsarray of stringsRequired

    List of data features that you would like to request access to. Possible values are balances, transactions, ownership, and payment_method.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • filtersobject

    Filters to restrict the kinds of accounts to collect.

    Show 3 child parameters
    • account_subcategoriesarray of strings
    • countriesarray of strings
    • require_payment_method_supportstring
      Possible values
      • all
      • at_least_one
      • none
  • limitsobject

    Settings for configuring Session-specific limits.

    Show 1 child parameter
    • accountsintegerRequired
  • manual_entryobject

    Customize manual entry behavior

    Show 1 child parameter
    • modestring
      Possible values
      • automatic
      • disabled
  • prefetcharray of strings

    List of data features that you would like to retrieve upon account creation.

  • return_urlstring

    For webview integrations only. Upon completing OAuth login in the native browser, the user will be redirected to this URL to return to your app.

Returns

The financial_connections.session object.

POST /v1/financial_connections/sessions
curl https://api.knoxapi.com/v1/financial_connections/sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "account_holder[type]=customer" \
  -d "permissions[]=balances"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_..._secret_...",
  "id": "fcsess_1Pgc76B7WZ01zgkWnYmFk7mZ",
  "livemode": false,
  "object": "financial_connections.session",
  "permissions": [
    "balances",
    "payment_method"
  ],
  "prefetch": []
}

List Transactions

GET/v1/financial_connections/transactions

Returns a list of Financial Connections Transaction objects.

Query parameters

  • accountstringRequired

    The ID of the Financial Connections Account whose transactions will be retrieved.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • transacted_atobject | integer

    A filter on the list based on the object transacted_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options:

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • transaction_refreshobject

    A filter on the list based on the object transaction_refresh field. The value can be a dictionary with the following options:

    Show 1 child parameter
    • afterstringRequired

Returns

A list of financial_connections.transaction objects.

GET /v1/financial_connections/transactions
curl -G https://api.knoxapi.com/v1/financial_connections/transactions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode account=fca_1Pgc76B7WZ01zgkWc69S5C3k
Response
{
  "object": "list",
  "url": "/v1/financial_connections/transactions",
  "has_more": false,
  "data": [
    {
      "account": "fca_1Pgc76B7WZ01zgkWc69S5C3k",
      "amount": 300,
      "currency": "usd",
      "description": "Rocket Rides",
      "id": "fctxn_1Pgc76B7WZ01zgkW30ATGSKp",
      "livemode": false,
      "object": "financial_connections.transaction",
      "status": "posted",
      "status_transitions": {
        "posted_at": 1721954068,
        "void_at": null
      },
      "transacted_at": 1234567890,
      "transaction_refresh": "fctxnref_QXhWc2Trdr6epyWGrcV9Qajf",
      "updated": 1234567890
    }
  ]
}

Retrieve an Account

GET/v1/financial_connections/accounts/{account}

Retrieves the details of an Financial Connections Account.

Path parameters

  • accountstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.account object.

GET /v1/financial_connections/accounts/{account}
curl https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "balance": {
    "as_of": 93102340,
    "current": {
      "undefined": 1126940025
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "category": "cash",
  "created": 1234567890,
  "display_name": "Sample Checking Account",
  "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
  "institution_name": "StripeBank",
  "last4": "6789",
  "livemode": false,
  "object": "financial_connections.account",
  "ownership": null,
  "ownership_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "permissions": [],
  "status": "active",
  "subcategory": "checking",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "obj_123",
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "account_numbers": null
}

Retrieve a Session

GET/v1/financial_connections/sessions/{session}

Retrieves the details of a Financial Connections Session

Path parameters

  • sessionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.session object.

GET /v1/financial_connections/sessions/{session}
curl https://api.knoxapi.com/v1/financial_connections/sessions/fcsess_1Pgc76B7WZ01zgkWnYmFk7mZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "accounts": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/financial_connections/accounts"
  },
  "client_secret": "fcsess_..._secret_...",
  "id": "fcsess_1Pgc76B7WZ01zgkWnYmFk7mZ",
  "livemode": false,
  "object": "financial_connections.session",
  "permissions": [
    "balances",
    "payment_method"
  ],
  "prefetch": []
}

Retrieve a Transaction

GET/v1/financial_connections/transactions/{transaction}

Retrieves the details of a Financial Connections Transaction

Path parameters

  • transactionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.transaction object.

GET /v1/financial_connections/transactions/{transaction}
curl https://api.knoxapi.com/v1/financial_connections/transactions/fctxn_1Pgc76B7WZ01zgkW30ATGSKp \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account": "fca_1Pgc76B7WZ01zgkWc69S5C3k",
  "amount": 300,
  "currency": "usd",
  "description": "Rocket Rides",
  "id": "fctxn_1Pgc76B7WZ01zgkW30ATGSKp",
  "livemode": false,
  "object": "financial_connections.transaction",
  "status": "posted",
  "status_transitions": {
    "posted_at": 1721954068,
    "void_at": null
  },
  "transacted_at": 1234567890,
  "transaction_refresh": "fctxnref_QXhWc2Trdr6epyWGrcV9Qajf",
  "updated": 1234567890
}

Disconnect an Account

POST/v1/financial_connections/accounts/{account}/disconnect

Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).

Path parameters

  • accountstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.account object.

POST /v1/financial_connections/accounts/{account}/disconnect
curl -X POST https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW/disconnect \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "balance": {
    "as_of": 93102340,
    "current": {
      "undefined": 1126940025
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "category": "cash",
  "created": 1234567890,
  "display_name": "Sample Checking Account",
  "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
  "institution_name": "StripeBank",
  "last4": "6789",
  "livemode": false,
  "object": "financial_connections.account",
  "ownership": null,
  "ownership_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "permissions": [],
  "status": "active",
  "subcategory": "checking",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "obj_123",
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "account_numbers": null
}

List Account Owners

GET/v1/financial_connections/accounts/{account}/owners

Lists all owners for a given Account

Path parameters

  • accountstringRequired

Query parameters

  • ownershipstringRequired

    The ID of the ownership object to fetch owners from.

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of financial_connections.account_owner objects.

GET /v1/financial_connections/accounts/{account}/owners
curl -G https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW/owners \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode ownership=fcaowns_1Pgc76B7WZ01zgkWuEXUc7bG
Response
{
  "object": "list",
  "url": "/v1/financial_connections/accounts",
  "has_more": false,
  "data": [
    {
      "email": "[email protected]",
      "id": "fcaown_1Pgc76B7WZ01zgkWIQ4dVcgH",
      "name": "Jane Smith",
      "object": "financial_connections.account_owner",
      "ownership": "fcaowns_1Pgc76B7WZ01zgkWuEXUc7bG",
      "phone": "+1 555-555-5555",
      "raw_address": "123 Main Street, Everytown USA",
      "refreshed_at": 1234567890
    }
  ]
}

Refresh Account data

POST/v1/financial_connections/accounts/{account}/refresh

Refreshes the data associated with a Financial Connections Account.

Path parameters

  • accountstringRequired

Body parameters

  • featuresarray of stringsRequired

    The list of account features that you would like to refresh.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.account object.

POST /v1/financial_connections/accounts/{account}/refresh
curl https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW/refresh \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "features[]=balance"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "balance": {
    "as_of": 93102340,
    "current": {
      "undefined": 1126940025
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "category": "cash",
  "created": 1234567890,
  "display_name": "Sample Checking Account",
  "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
  "institution_name": "StripeBank",
  "last4": "6789",
  "livemode": false,
  "object": "financial_connections.account",
  "ownership": null,
  "ownership_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "permissions": [],
  "status": "active",
  "subcategory": "checking",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "obj_123",
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "account_numbers": null
}

Subscribe to data refreshes for an Account

POST/v1/financial_connections/accounts/{account}/subscribe

Subscribes to periodic refreshes of data associated with a Financial Connections Account. When the account status is active, data is typically refreshed once a day.

Path parameters

  • accountstringRequired

Body parameters

  • featuresarray of stringsRequired

    The list of account features to which you would like to subscribe.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.account object.

POST /v1/financial_connections/accounts/{account}/subscribe
curl https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW/subscribe \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "features[]=transactions"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "balance": {
    "as_of": 93102340,
    "current": {
      "undefined": 1126940025
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "category": "cash",
  "created": 1234567890,
  "display_name": "Sample Checking Account",
  "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
  "institution_name": "StripeBank",
  "last4": "6789",
  "livemode": false,
  "object": "financial_connections.account",
  "ownership": null,
  "ownership_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "permissions": [],
  "status": "active",
  "subcategory": "checking",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "obj_123",
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "account_numbers": null
}

Unsubscribe from data refreshes for an Account

POST/v1/financial_connections/accounts/{account}/unsubscribe

Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.

Path parameters

  • accountstringRequired

Body parameters

  • featuresarray of stringsRequired

    The list of account features from which you would like to unsubscribe.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The financial_connections.account object.

POST /v1/financial_connections/accounts/{account}/unsubscribe
curl https://api.knoxapi.com/v1/financial_connections/accounts/acct_1PgafTB7WZ01zgkW/unsubscribe \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "features[]=transactions"
Response
{
  "account_holder": {
    "customer": "cus_QXg1o8vcGmoR32",
    "type": "customer"
  },
  "balance": {
    "as_of": 93102340,
    "current": {
      "undefined": 1126940025
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "category": "cash",
  "created": 1234567890,
  "display_name": "Sample Checking Account",
  "id": "fca_1Pgc76B7WZ01zgkWqlYVCIub",
  "institution_name": "StripeBank",
  "last4": "6789",
  "livemode": false,
  "object": "financial_connections.account",
  "ownership": null,
  "ownership_refresh": {
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "permissions": [],
  "status": "active",
  "subcategory": "checking",
  "subscriptions": [],
  "supported_payment_method_types": [
    "us_bank_account"
  ],
  "transaction_refresh": {
    "id": "obj_123",
    "last_attempted_at": 1981828143,
    "next_refresh_available_at": null,
    "status": "failed"
  },
  "account_numbers": null
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.