Transactions and balances with Kolo

This feature is in beta, so things may be a little flaky at the edges. We’re always grateful for feedback to help us improve it: email [email protected].

Kolo is a financial management application that consolidates a user’s bank accounts into a single platform, letting them view balances, track transactions, and categorize spending. This API extends Kolo’s functionality so you can integrate it into your own application, tracking your customers’ bank balances and transactions to get a picture of their financial health.

Getting started

To use the Kolo API, your customer needs to:

• Create an account: sign up for Kolo.
• Grant permissions: authorize your app to access their bank account information.

The Kolo API uses OAuth 2.0 for authentication. Make sure you have valid credentials and complete the authorization steps below before calling the other endpoints.

Initializing authorization

To access a customer’s data through Kolo, you exchange an authorization code for an access token.

Step 1: Obtain an authorization code

Redirect the user to the Kolo authorization URL so they can grant your app consent to access their data:

GET https://app.kolo.finance/data-share?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}

Parameter	Description
response_type	Set this to code to receive an authorization code.
client_id	Your app’s client ID, from Developer > Apps in your admin console.
redirect_uri	The URI to redirect to after authorization: an endpoint you control.
scope	The scope(s) of the access request (for example transaction:list).

Example request:

GET https://app.kolo.finance/data-share?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=transaction:list

Step 2: Exchange the authorization code for an access token

Once the user authorizes your app, they’re redirected to your redirect_uri with an authorization code. Exchange it for an access token:

POST https://adjutor.lendsqr.com/v2/kolo/auth

Parameter	Description
code	The authorization code received in Step 1.
grant_type	Set this to authorization_code.
redirect_uri	The same redirect URI used in Step 1.

curl --location 'https://adjutor.lendsqr.com/v2/kolo/auth' \
--header 'Authorization: Bearer {your_api_key}' \
--data '{
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code",
    "code": "kEhA1fQsT86ZxCqh"
}'

Step 3: Receive the access token

{
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "username": "username",
    "scope": "transaction:list",
    "token_type": "Bearer"
}

Field	Description
access_token	The token to use for authenticated requests.
token_type	Type of token, typically “Bearer”.
username	The name of the user.
refresh_token	Token used to refresh the access token.
scope	Scopes granted by the access token.

Using your access token

Include the access token in the x-access-token header of your requests:

curl --location 'https://adjutor.lendsqr.com/v2/kolo/transactions' \
--header 'x-access-token: {your_access_token}'

Refreshing the access token

Access tokens expire quickly. When yours does, use the refresh token to get a new one:

POST https://adjutor.lendsqr.com/v2/kolo/auth

Parameter	Description
code	Your refresh token.
grant_type	Set this to refresh_token.
redirect_uri	The same redirect URI used in the original authorization request.

{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "username": "customer's username",
  "scope": "transaction:list"
}

Permission scopes

Kolo uses scopes to control access to a customer’s account. Request only the scopes you need, and state them explicitly: any scope not clearly defined in your authorization URL won’t be usable, even implicitly.

Scope	Description
transaction:list	List all transactions.
transaction:view	View details of a specific transaction.
transaction:update	Update a specific transaction.
bank_account:list	List all bank accounts.
bank_account:view	View details of a specific bank account.
bank_account:add	Add a new bank account.
bank_account:update	Update a specific bank account.
bank_account:delete	Delete a specific bank account.
bank_account:sync	Synchronize a specific bank account.
profile:view	View the user’s profile.

Questions or feedback on this beta? Email [email protected].