Skip to main content
POST
/
link-session
/link-session
curl --request POST \
  --url http://localhost:8080/link-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "settings": {
    "providers": [
      "moneykit"
    ],
    "link_permissions": {
      "requested": [
        {
          "scope": "accounts",
          "reason": "display your account balances",
          "required": true
        }
      ]
    },
    "products": {
      "account_numbers": {
        "required": false,
        "prefetch": false,
        "product": "accounts"
      },
      "identity": {
        "required": false,
        "prefetch": false,
        "product": "accounts"
      },
      "transactions": {
        "required": false,
        "prefetch": false,
        "product": "accounts",
        "extend_history": false
      },
      "investments": {
        "required": false,
        "prefetch": false,
        "product": "accounts"
      }
    },
    "countries": [
      "US"
    ]
  },
  "customer_user": {
    "id": "<string>",
    "email": {
      "address": "<string>",
      "customer_verified_at": "2023-02-16T00:00:00"
    },
    "phone": {
      "number": "+16175551212",
      "country": "US",
      "customer_verified_at": "2023-02-16T00:00:00"
    }
  },
  "existing_link_id": "mk_eqkWN34UEoa2NxyALG8pcV",
  "institution_id": "c7318ff7-257c-490e-8242-03a815b223b7",
  "redirect_uri": "https://yourdomain.com/oauth.html",
  "webhook": "https://yourdomain.com/moneykit_webhook",
  "link_tags": [
    "smoke_test",
    "user_type:admin"
  ],
  "connect_features": {
    "issue_reporter": false,
    "enable_money_id": false
  }
}'
{
  "link_session_token": "c7318ff7-257c-490e-8242-03a815b223b7"
}
curl -i -X POST \
  http://localhost:8080/link-session \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'moneykit-version: 2023-02-18' \
  -d '{
    "settings": {
      "providers": [
        "moneykit"
      ],
      "link_permissions": {
        "requested": [
          {
            "scope": "accounts",
            "reason": "display your account balances",
            "required": true
          }
        ]
      },
      "products": {
        "account_numbers": {
          "required": false,
          "prefetch": false
        },
        "identity": {
          "required": false,
          "prefetch": false
        },
        "transactions": {
          "required": false,
          "prefetch": false,
          "extend_history": false
        }
      },
      "countries": [
        "US"
      ]
    },
    "customer_user": {
      "id": "string",
      "email": {
        "address": "string",
        "customer_verified_at": "2023-02-16T00:00:00"
      },
      "phone": {
        "number": "+16175551212",
        "country": "US",
        "customer_verified_at": "2023-02-16T00:00:00"
      }
    },
    "existing_link_id": "mk_eqkWN34UEoa2NxyALG8pcV",
    "institution_id": "c7318ff7-257c-490e-8242-03a815b223b7",
    "redirect_uri": "https://yourdomain.com/oauth.html",
    "webhook": "https://yourdomain.com/moneykit_webhook",
    "link_tags": [
      "smoke_test",
      "user_type:admin"
    ],
    "moneylink_features": {}
  }'

{
  "link_session_token": "c7318ff7-257c-490e-8242-03a815b223b7"
}

{
  "webhook_event": "link.state_changed",
  "webhook_major_version": 1,
  "webhook_minor_version": 0,
  "webhook_idempotency_key": "string",
  "webhook_timestamp": "2019-08-24T14:15:22Z",
  "link_id": "string",
  "link_tags": [
    "string"
  ],
  "state": "connecting",
  "error": "system_error",
  "error_message": "string"
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
moneykit-version
string
default:2023-02-18

Body

application/json
​
customer_user
object
required

Details about your end user. These details are used to improve conversion and streamline the linking flow, and to support the MoneyID system, which provides enhanced debugging and improved privacy controls for your end user.

​
redirect_uri
string<uri>
required

For Oauth linking, a URI indicating the destination, in your application, where the user should be sent after authenticating with the institution. The redirect_uri should not contain any query parameters, and it must be pre-approved by MoneyKit during the customer setup process.

Required string length: 1 - 65536
Example:

"https://yourdomain.com/oauth.html"

​
settings
object

If provided, these settings will override your default settings for this session.

​
existing_link_id
string

Supply the existing link_id if you are asking the user to reconnect this link.

Example:

"mk_eqkWN34UEoa2NxyALG8pcV"

​
institution_id
string

The ID of the institution you want to link to. Providing this will skip the institution selection step. existing_link_id will take precedence over this field if both are provided.

Example:

"c7318ff7-257c-490e-8242-03a815b223b7"

​
webhook
string<uri>

The destination URL to which any webhooks should be sent.

Required string length: 1 - 65536
Example:

"https://yourdomain.com/moneykit_webhook"

​
link_tags
string[]

You can supply one or more arbitrary strings as tags to describe this link.

Example:
["smoke_test", "user_type:admin"]
​
connect_features
object

Enables optional testing and UI features.

Response

Successful Response

​
link_session_token
string
required

A unique token identifying this link session.

Example:

"c7318ff7-257c-490e-8242-03a815b223b7"