Create Session

Changed on Nov 3, 2026

Create a session and use it to initialize the SDK.

post/session/create

Request

Base URL
https://development.knotapi.com
URL
https://development.knotapi.com/session/create
Auth
HTTP basic

Request body

type'card_switcher' | 'transaction_link' | 'link' | 'vault' required

Product to associate the session with.

external_user_idstring required

Your unique identifier for the user.

card_idstring nullable

Your unique identifier for a specific card. Required when type = card_switcher. Optionally accepted when type = vault.

bank_account_idstring nullable

Your unique identifier for a specific bank account. Only accepted when type = card_switcher. When provided, the user can switch a bank account instead of a card at supported merchants. card_id is still required.

emailstring nullable

User's email address. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.

phone_numberstring nullable

User's phone number in E.164 format. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.

country'US' | 'CA'

Country of the user (ISO 3166-1 alpha-2, upper case). Determines which merchants are available in the session and is applied to the merchant accounts the user links in it. Omit the field to use your default country, which is US unless your account is set up for a single other country. A country that is not enabled for your account returns a 403.

processor_tokenstring nullable

Plaid processor_token if using transaction data from Plaid to detect merchants.

metadataobject nullable

Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.

Example request

{
  "type": "card_switcher",
  "external_user_id": "123abc",
  "card_id": "81n9al10a0ayn13",
  "bank_account_id": "91n9al81da0k1yn13",
  "email": "ada.lovelace@gmail.com",
  "phone_number": "+11234567890",
  "country": "CA",
  "metadata": {
    "reference_token": "abc123",
    "trace_id": "def456"
  }
}

Response

Successful request.

sessionstring

A session.

Example response

{
  "session": "915efe72-5136-4652-z91q-d9d48003c102"
}

Changes

Nov 3, 2026f10ecfa12c00 Revision changes
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property

Operation history