API reference

Linked Accounts

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/linked_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/linked_accounts
curl -G https://api.knoxapi.com/v1/linked_accounts \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/linked_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
    }
  ]
}

Retrieve an Account

GET/v1/linked_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/linked_accounts/{account}
curl https://api.knoxapi.com/v1/linked_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
}

Disconnect an Account

POST/v1/linked_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/linked_accounts/{account}/disconnect
curl -X POST https://api.knoxapi.com/v1/linked_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/linked_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/linked_accounts/{account}/owners
curl -G https://api.knoxapi.com/v1/linked_accounts/acct_1PgafTB7WZ01zgkW/owners \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode ownership=fcaowns_1Pgc76B7WZ01zgkWuEXUc7bG
Response
{
  "object": "list",
  "url": "/v1/linked_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/linked_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/linked_accounts/{account}/refresh
curl https://api.knoxapi.com/v1/linked_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
}

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.