Institutional-level report

7min
Get institution level products by institutionCode and end-user's taxId.
This endpoint is a notification API. After the end user completes authorization on the bank side, the Klavi backend will return the user's authorization information through webhook. Then, partners can send the data products required by the partners based on the authorization information through this notification endpoint.
When Klavi receives this request from partner, Klavi backend immediately retrieves the data through open finance and processes it into specific data products, which is then sent to the partner through webhook.
Products may be requested by different applications, disregarding the original application to which the user gave consent.
POST
Request
Header Parameters
Authorization
required
String
Bearer access token, it returned by the /auth
Body Parameters
taxId
required
String
The CPF of the end-user, for Personal Accounts only
institutionCode
required
String
Institution identity
linkId
optional
String
linkId, it returned by the /links
consentIds
optional
Array
consentId list, it returned by the /consents
products
required
Array
Product list
productsCallbackURL
optional
Object
Report products callback URL,
Priority highest
externalInfo
optional
Object
Used for partner to transmit information, which will be carried in reports sent to partner
Curl
curl --location 'https://api-sandbox.klavi.ai/data/v1/personal/institution-data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"taxId":"string","institutionCode":"string","linkId":"String","consentIds":["Array"],"products":["Array"],"productsCallbackURL":"Object","externalInfo":"Object"}'
curl --location 'https://api-sandbox.klavi.ai/data/v1/personal/institution-data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"taxId":"string","institutionCode":"string","linkId":"String","consentIds":["Array"],"products":["Array"],"productsCallbackURL":"Object","externalInfo":"Object"}'
Responses
200
{
    "requestId": "xxxsssaa",
    "message": "ok"
}
{
    "requestId": "xxxsssaa",
    "message": "ok"
}
﻿
Parameter
products
all: All institutional level products﻿ selected by partners during onboarding;
product list: One or more institutional level products﻿(can only be products within the product range selected by the partner during onboarding);
productsCallbackURL
With this parameter, you can submit specific or all reports generated sending addresses to Klavi backend.
1.Specific reports example
JSON
{
    "productsCallbackURL":{
        "pf_checking_account":"https://www.yourdomain.com/checking/yourpath",
        "pf_credit_card":"https://www.yourdomain.com/creditcard/yourpath"
    }
}
{
    "productsCallbackURL":{
        "pf_checking_account":"https://www.yourdomain.com/checking/yourpath",
        "pf_credit_card":"https://www.yourdomain.com/creditcard/yourpath"
    }
}
﻿
After the report is generated, the Klavi backend will send the report pf_checking_account to  https://www.yourdomain.com/checking/yourendpoint and send the report pf_credit_card to https://www.yourdomain.com/creditcard/yourpath.
2.Specific and other reports example
JSON
{
    "productsCallbackURL":{
        "pf_checking_account":"https://www.yourdomain.com/checking/yourpath",
        "other":"https://www.yourdomain.com/yourpath"
    }
}
{
    "productsCallbackURL":{
        "pf_checking_account":"https://www.yourdomain.com/checking/yourpath",
        "other":"https://www.yourdomain.com/yourpath"
    }
}
﻿
In this case, the Klavi backend will send the report pf_checking_account to  https://www.yourdomain.com/checking/yourendpoint and send the other report to https://www.yourdomain.com/yourpath.
3.All reports example
JSON
{
    "productsCallbackURL":{
        "all":"https://www.yourdomain.com/yourpath"
    }
}
{
    "productsCallbackURL":{
        "all":"https://www.yourdomain.com/yourpath"
    }
}
﻿
After the report is generated, the Klavi backend will send all reports(You selected it when you onborading) to https://www.yourdomain.com/yourpath.
Please note that:
The parameter all is mutually exclusive with the parameters other and specific and cannot exist simultaneously. If it exists, the system will return an error.
Report generation logic
The Klavi backend will determine the data range for generating reports based on the parameters you submit.
taxId: If you only submit this parameter, the Klavi backend system will aggregate all consents data ranges of all links around the taxId for report calculation and generation.
linkId: If you submit this parameter and taxId(Required),  the Klavi backend system will aggregate this linkId data ranges of the taxId for report calculation and generation.
consentId: If you submit this parameter and taxId(Required), the Klavi backend system will aggregate this consentId data ranges of the taxId for report calculation and generation.
externalInfo
You can submit any content you want with this parameter, and Klavi will temporarily save it. After the report is generated, it will be returned to you in the externalInfo data node of the report.
For example:
JSON
{
    "externalInfo":{
        "myTraceId":"yourtraceid",
        "myUUID":"youruuid"
    }
}
{
    "externalInfo":{
        "myTraceId":"yourtraceid",
        "myUUID":"youruuid"
    }
}
﻿
﻿
Updated 29 Sep 2024
Did this page help you?
Revoke a Consent
User-level report