📘
In this section, you will learn how to connect with a financial institution and access your employment data like Employee Information, General Information, and Salary Information.

Brick is currently offering two environments:

Sandbox, a sandbox environment with test data perfect for test and development phases.
Production, a live environment used in production with real connections to institutions.

To generate your keys for each environment, have a look to our guide to get your Brick API keys or Sign Up now!

📘
In the following examples we will use the sandbox environment.
Change the base URL to https://api.onebrick.io for each example to switch to production.

Step 1: Generate a JWT bearer token (Public access token)

Use your Sandbox API keys viz. a ClientID & ClientSecret with the generate public token api to get a JWT((JSON Web Token). This JWT or what we call a public access token can be used to launch the Brick widget and access institution list.

curl -u Client ID:Client Secret https://sandbox.onebrick.io/v1/auth/token

{
    "status": 200,
    "message": "OK",
    "data": {
        "access_token": "public-sandbox-b70bcf83-87a1-4f2c-8f2a-16d48021413a"
    }
}

Response Parameter

Key Parameter	Data Type	Description
access_token	string	Token that is required to connect Brick API

Step 2: Launch Brick Widget (Option 1)

Use the JWT/public-access-token to launch the brick widget in your application and let your users connect their financial Institution accounts with your application.
To launch the brick UI widget you need to construct the URL in the following format-
https://cdn.onebrick.io/sandbox-widget/v1/?accessToken=public-sandbox-access-token

📘
Notice that the URL above is a newer version ( V1 ) of our Brick Widget that contained a new feature inside comparing to the old version. Currently, we still offer you our old Brick Widget where your end-user can only connect a single account at a time ( https://cdn.onebrick.io/sandbox-widget/?accessToken=public-sandbox-access-token ) until further notice.
Therefore, we encourage you to integrate and experienced our newest feature on Brick Widget as soon as possible where your end-user have the ability to connect multiple accounts/institutions in single flow.
P.S : This feature would be very helpful for you to have as much information from the connected accounts/institutions from your end-users.

There are some optional parameters that can be added to above url for customizations which can be seen here.

Read the Brick Widget Section to see in-depth integration steps.

Step 2: API Connection (Option 2)

Use the JWT/public-access-token to authenticate your user via connection to our API with these inputs in order to generate clientId and redirectRefId which will be used in the next step in order to generate user-access-token from your user's account

curl --request POST 'https://sandbox.onebrick.io/v1/auth' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer public_access_token' \
--data-raw '{
    "institution_id": 41,
    "username": "[email protected]",
    "password": "password1234!"
}'

Key Parameter	Data type	Description
accessToken	String	Public-access-token generated using your clientId and clientSecret
institution_id	Integer	Unique Institution Id for every institutions, For Ajaib it's 41
username	String	End-users username of Investment Platform account
password	String	End-users password of Investment Platform account

If the authentication is successful, you will receive the success responses asking for additional authentication input which is PIN.

{
    "status": 428,
    "message": "a PIN is required by the institution to login",
    "data": {
        "sessionId": "675134b4-fe34-47dc-a5d0-05ec01264d1d-20220608160350",
        "username": "[email protected]  ",
        "duration": "50000"
    }
}

Key Parameter	Data Type	Description
sessionId	String	Unique Id that generated after successful connection
username	String	End-users username of Investment Platform account
duration	Float	Duration of the sessionId validity before it expired

After you get this response, you can proceed the authentication process to generate user-access-token with these inputs, the sessionId is the sessionId that was retrieved from the previous authentication request

curl --request POST 'https://sandbox.onebrick.io/v1/auth/ajaib' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer public_access_token' \
--data-raw '{
    "institution_id": 41,
    "sessionId": "be0164de-060a-493f-b7c0-c40e4fe36ef3-2022060816090",
    "username": "[email protected]",
    "password": "password1234!",
    "pin": 5555
}'

Key Parameter	Data Type	Description
institutionId	Integer	Unique Institution Id for every institutions, For Ajaib it's 41
sessionId	String	Unique Id that generated after successful connection
username	String	End-users username of Investment Platform account
password	String	End-users password of Investment Platform account
pin	Integer	End-users PIN of Investment Platform account

If the authentication is successful, you will receive the success responses along with the user-access-token

{
  "status": 200,
  "message": "OK",
  "data": {
    "accessToken": "user_access_token",
  }
}

Key Parameter	Data Type	Description
accessToken	Integer	Access_token to identify end-users

Step 3: Profile Information

Retrieve investment account's profile data of your end-users.

Using the previously created user-access-token in Step 2, we can now retrieve the general information of the user.

curl https://sandbox.onebrick.io/v1/assets/profile
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

The api responds with accounts associated with the user who logged in using the Brick widget.

{
    "status": 200,
    "message": "OK",
		"lastUpdateAt": "2022-01-04 16:42 GMT+0700",
		"session": "valid",
    "data": {
        "sid": "IDD0706B572000",
        "name": "Pasek Sujana",
        "phone": "081806000000",
        "email": "[email protected]",
        "risk_profile": "Low - Medium Risk",
        "bank_account": [
            {
                "bank_name": "Bank Central Asia (BCA)",
                "holder": "Pasek Sujana",
                "number": "4491320000",
                "balance": 0.0,
                "type": "Personal"
            },
            {
                "bank_name": "BCA",
                "holder": "Pasek Sujana",
                "number": "4996740000",
                "balance": 133520.0,
                "type": "RDN"
            }
        ]
    }
}

Response Parameter

Key Parameter	Data Type	Description
sid	String	Single Investor Identification number of the End User
name	String	Name of the End User
phone	String	Phone Number of the End User
email	String	Email of the End User
risk_profile	String	Risk Profile of the End User
bank_name	String	Bank Name of the End User's account
holder	String	Bank account holder's name
number	String	Bank account's number
balance	Float	Bank account's balance
type	String	Bank account's type (RDN / Personal)

Step 4: Portfolio Information

Retrieve investment account's portfolio data of your end-users.

Using the previously created user-access-token in Step 2, we can now retrieve the portfolio information list of users.

curl https://sandbox.onebrick.io/v1/assets/portfolio
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

The api responds with accounts associated with the user who logged in using the Brick widget.

{
    "status": 200,
    "message": "OK",
    "lastUpdateAt": "2022-01-04 16:42 GMT+0700",
		"session": "valid",
    "data": [
        {
            "asset_type": "stocks",
            "total_investment": 34200.0,
            "total_return": -5600.0,
            "return_percentage": "-14,07%",
            "equity_summary": 39800.0,
            "assets_list": [
                {
                    "name": "CPRO",
                    "lot": 1.0,
                    "amount": 10000.0,
                    "total": 7300.0,
                    "percentage": "-27%",
                    "type": "",
                    "average_value": 100.0,
                    "current_value": 73.0,
                    "return": -2700.0
                },
                {
                    "name": "FREN",
                    "lot": 2.0,
                    "amount": 17600.0,
                    "total": 17200.0,
                    "percentage": "-2,27%",
                    "type": "",
                    "average_value": 88.0,
                    "current_value": 86.0,
                    "return": -400.0
                },
                {
                    "name": "KPIG",
                    "lot": 1.0,
                    "amount": 12200.0,
                    "total": 9700.0,
                    "percentage": "-20,49%",
                    "type": "",
                    "average_value": 122.0,
                    "current_value": 97.0,
                    "return": -2500.0
                }
            ]
        },
        {
            "asset_type": "mutual_funds",
            "total_investment": 31093.0,
            "total_return": 1093.0,
            "return_percentage": "3,65%",
            "equity_summary": 30000.0,
            "assets_list": [
                {
                    "name": "BNI AM Dana Likuid",
                    "lot": 5.8291,
                    "amount": 10000.0,
                    "total": 10084.0,
                    "percentage": "+0,84%",
                    "type": "Pasar Uang",
                    "average_value": 1716.0,
                    "current_value": 1730.0,
                    "return": 84.0
                },
                {
                    "name": "Syailendra Balanced Opportunity Fund Kelas A",
                    "lot": 6.2822,
                    "amount": 20000.0,
                    "total": 21010.0,
                    "percentage": "+5,05%",
                    "type": "Campuran",
                    "average_value": 3184.0,
                    "current_value": 3344.0,
                    "return": 1010.0
                }
            ]
        }
    ]
}

Response Parameter

Key Parameter	Data Type	Description
asset_type	String	Type of investment asset (stocks / mutual funds / bonds)
total_investment	Float	The total investment made for the asset type
total_return	Float	The total return of the investment made *can be negative
return_percentage	String	The return percentage of the investment made *can be negative
equity_summary	Float	The current equity summary of total investment added/subtracted to total return
assets_list	String	The list of the assets that falls under the asset type
name	String	The name of the assets (For example CPRO for stocks, BNI AM Dana Likuid for mutual funds)
lot	Float	The lot amount of the assets
amount	Float	The initial value amount of the assets
total	Float	The current value amount of the assets
percentage	String	The return percentage of the assets *can be negative
type	String	The type of assets (For mutual funds example: Pasar Uang, Pasar Saham)
average_value	Float	The initial average value of the assets
current_value	Float	The current value of the assets
return	Float	The total return of the assets *can be negative

Step 5: Transactions Information

Retrieve investment account's transactional data of your end-users.

Using the previously created user-access-token in Step 2, we can now retrieve the transactions list of users.

curl https://sandbox.onebrick.io/v1/assets/transactions?from=YYYY-MM-DD&to=YYYY-MM-DD
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer user-access-token'

Where, [user-access-token] is the access token generated after successful institution connection through the widget which needs to be passed as the Bearer token in the Authorization header and from with starting date that you want to retrieve from transaction from, and to with ending date that you want to retrieve your transaction to.

The api responds with accounts associated with the user who logged in using the Brick widget.

{
    "status": 200,
    "message": "OK",
    "lastUpdateAt": "2022-01-04 16:42 GMT+0700",
		"session": "valid",
    "data": [
        {
            "direction": "buy",
            "asset_type": "stocks",
            "name": "KPIG",
            "type": "",
            "date": "2022-02-10",
            "time": "1644484560",
            "lot": "1",
            "average_value": "122",
            "amount": "12200",
            "fee": "18",
            "status": "Done"
        },
        {
            "direction": "sell",
            "asset_type": "stocks",
            "name": "CPRO",
            "type": "",
            "date": "2022-02-10",
            "time": "1644484080",
            "lot": "1",
            "average_value": "103",
            "amount": "10300",
            "fee": "26",
            "status": "Done"
        },
        {
            "direction": "sell",
            "asset_type": "mutual_funds",
            "name": "Eastspring Investments Value Discovery Kelas A",
            "type": "Saham",
            "date": "2022-02-13",
            "time": "1644782640",
            "lot": "7.4062",
            "average_value": "1343",
            "amount": "9947",
            "fee": "0",
            "status": "Permintaan Penarikan Berhasil"
        },
        {
            "direction": "buy",
            "asset_type": "mutual_funds",
            "name": "Eastspring Investments Value Discovery Kelas A",
            "type": "Saham",
            "date": "2022-02-09",
            "time": "1644413220",
            "lot": "7.4062",
            "average_value": "1350",
            "amount": "10000",
            "fee": "0",
            "status": "Unit Diterima"
        }
    ]
}

Response Parameter

Key Parameter	Data Type	Description
direction	String	The direction of transaction made (buy / sell)
asset_type	String	Type of investment asset (stocks / mutual_funds / bonds)
name	String	The name of the assets (For example CPRO for stocks, BNI AM Dana Likuid for mutual funds)
type	String	The type of assets (For mutual funds example: Pasar Uang, Pasar Saham)
date	Date	The date of the transaction made
time	String	The time of the transaction made
lot	Float	The lot amount of the assets
average_value	Float	The initial average value of the assets
amount	Float	The amount of the transaction
fee	Float	The fee of the transaction
status	String	The status of the transaction

Step 6: Refresh Expired Session and Retrieve Transactions

When the investment account session is expired, Brick will return the last updated transaction data of the user with the specified time of the update in the "lastUpdateAt" variables, for example "lastUpdateAt": "2022-01-04 16:42 GMT+0700" as well as the status of the session itself in the "session" variable, for example "session": "expired" or "valid".

Let's take the Profile APIs for example:

{
    "status": 200,
    "message": "OK",
		"lastUpdateAt": "2022-01-04 16:42 GMT+0700",
		"session": "expired",
    "data": {
        "sid": "IDD0706B572000",
        "name": "Pasek Sujana",
        "phone": "081806000000",
        "email": "[email protected]",
        "risk_profile": "Low - Medium Risk",
        "bank_account": [
            {
                "bank_name": "Bank Central Asia (BCA)",
                "holder": "Pasek Sujana",
                "number": "4491320000",
                "balance": 0.0,
                "type": "Personal"
            },
            {
                "bank_name": "BCA",
                "holder": "Pasek Sujana",
                "number": "4996740000",
                "balance": 133520.0,
                "type": "RDN"
            }
        ]
    }
}

When the session variable returns "expired", client needs to refresh the investment account session and access the fresh transaction data, there's two steps that needs to be done:

1. Making a POST request to trigger an OTP to be sent to user

curl --request POST 'https://sandbox.onebrick.io/v1/assets-mfa/profile' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer user_access_token' \

Where [user-access-token] is the access token generated after successful Financial Institution connection through the widget which needs to be passed as the Bearer token in the Authorization header.

After you have click the send POST request, you will get JSON response like the following and an OTP will be sent to users.

{
    "status": 428,
    "message": "An OTP is required by the institution to login",
    "data": {
        "sessionId": "iy1eEwyo1N6R7S8zDuHOKMHxYGpo9U",
        "requestId": "00b58118-cedf-47c6-9c82-6e656fbdbe42",
        "token": null,
        "duration": 180000
    }
}

Key Parameter	Data Type	Description
sessionId	String	Session identification of that request
requestId	String	Request identification of that request
duration	Float	Duration expiration for sessionId

2. Making a PATCH request and providing the sessionId that is received from previous POST request and OTP that is sent to user after making previous POST request

Using the sessionId retrieved from the previous request, the OTP that is sent to user and also the specified from and to date, you can use it to make a new PATCH request to the following link

curl --request PATCH 'https://sandbox.onebrick.io/v1/assets-mfa/profile' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer user_access_token' \
--form 'token="1111"' \
--form 'sessionId="whVOGr1SpBNFH0dJ3PjupheSWXU31t"'

The api responds with accounts associated with the user who logged in using the Brick widget and a "valid" session due to the previous POST and PATCH API Process.

{
    "status": 200,
    "message": "OK",
		"lastUpdateAt": "2022-01-04 16:42 GMT+0700",
		"session": "valid",
    "data": {
        "sid": "IDD0706B572000",
        "name": "Pasek Sujana",
        "phone": "081806000000",
        "email": "[email protected]",
        "risk_profile": "Low - Medium Risk",
        "bank_account": [
            {
                "bank_name": "Bank Central Asia (BCA)",
                "holder": "Pasek Sujana",
                "number": "4491320000",
                "balance": 0.0,
                "type": "Personal"
            },
            {
                "bank_name": "BCA",
                "holder": "Pasek Sujana",
                "number": "4996740000",
                "balance": 133520.0,
                "type": "RDN"
            }
        ]
    }
}

For more APIs Reference, please access it through Investment Data APIs

Conclusion

Using this step by step guide you have been able to get a first preview on Brick's API for investment data and how to integrate Brick in your website or application