API Reference

Create a session

The /session/create endpoint creates a session ID, which is required as a parameter when initializing the SDK.
Initialize the SDK with the same session, to show the user the state they left off on (OTP Required, Invalid Credentials, Success, etc.), or you can initialize the SDK with a new session to show the user a fresh state.

📘

Expiration

Sessions will expire after 30 minutes.

Endpoint

POST https://development.knotapi.com/session/create

Request fields

Field NameTypeDescription
typerequired, stringThe SDK that will be initialized. This should be set to card_switcher.
external_user_idrequired, string or numberYour internal user identifier.
card_idrequired, string or numberYour internal card identifier.
phone_numberstringThe user's phone number in E.164 format.
emailstringThe user's email.
card.blockedbooleanDetermines if the card is blocked
card.has_fundsbooleanDetermines if the card has funds
processor_tokenstringProcessor token from bank connectivity aggregator that allows for Knot to customize the merchant transaction list within the SDK
curl -X POST 'https://development.knotapi.com/session/create' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "type": "card_switcher",
    "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
    "card_id": 12345,
    "phone_number": "+14155550123",
    "email": "[email protected]"
  }'

curl -X POST 'https://development.knotapi.com/session/create' \
  -u "bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108" \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "type": "card_switcher",
    "external_user_id": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3",
    "card_id": 12345,
    "phone_number": "+14155550123",
    "email": "[email protected]",
    "phone_number": {
      "blocked": false,
      "has_funds" true
    }
  }'

Response example

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

Extend session

The /session/extend endpoint extends an existingsession ID for another 30 minutes. The extended session contains the same state as the previous session.

Endpoint

POST https://development.knotapi.com/session/extend

Request fields

Field NameTypeDescription
session_idrequired, stringYour session ID.
curl -X POST 'https://development.knotapi.com/session/extend' \
  -u 'bd271e95-14e6-47ab-9f4f-225898f69183:cf819749c0574616ba93b5935b8cf108' \
  -H 'Content-Type: application/json' \
  -H 'Knot-Version: 2.0' \
  -d '{
    "session_id": "915efe72-5136-4652-z91q-d9d48003c102"
  }'

Response example

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