Create a Link

8min

Create a link by accessToken
POST
Request
Header Parameters
Authorization
String
required
Bearer access token, it returned by the /auth
Body Parameters
personalTaxId
String
optional
The CPF of the end-user, for Personal Accounts only
businessTaxId
String
optional
The CNPJ of the company, for Business Accounts only
email
String
optional
End user's email, compliance needs
phone
String
optional
End user's phone, compliance needs
institutionCode
String
optional
Pre set parameters, the purpose is to avoid users choosing specific institutions
redirectURL
String
optional
The URL for redirection upon successful link initialization
productsCallbackURL
Object
optional
Report products callback URL, for Open finance only
externalInfo
Object
optional
Used for partners to transmit information, which will be carried in reports sent to partners. 
connectionKey
String
optional
Connection key, the connectionKey has been sent to the partner in the report, for Open data update case only
appLink
String
optional
After the institution authorization is completed, it will jump to this appLink with the appRedirectURLKey parameter
appRedirectURLKey
String
optional
Partners can customize this parameter according to your actual situation.
If parameter appLink exists, this parameter must be exist.
Curl
curl --location 'https://api-sandbox.klavi.ai/data/v1/links' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalTaxId":"string","businessTaxId":"string","email":"string","phone":"string","institutionCode":"String","redirectURL":"string","productsCallbackURL":"Object","externalInfo":"Object","connectionKey":"string"}'
curl --location 'https://api-sandbox.klavi.ai/data/v1/links' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalTaxId":"string","businessTaxId":"string","email":"string","phone":"string","institutionCode":"String","redirectURL":"string","productsCallbackURL":"Object","externalInfo":"Object","connectionKey":"string"}'
Responses
200
{
    "linkId": "4437b139-8a16-11ee-b636-487b6bad036a",
    "linkURL": "https://conecte-sandbox.klavi.ai/path?v=AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD",
    "linkToken": "AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD",
    "expireIn": 1800
}
{
    "linkId": "4437b139-8a16-11ee-b636-487b6bad036a",
    "linkURL": "https://conecte-sandbox.klavi.ai/path?v=AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD",
    "linkToken": "AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD",
    "expireIn": 1800
}
﻿
If you were a klavi customer before 22/11/2024, you may be able to use the links according to the old nomenclature, then, the linkURL response may look like:
https://open-sandbox.klavi.ai/path?v=AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD
﻿
Parameter
redirectURL
The end-user completes authorization and returns to the client's page URL from the LGDP page.
 If authorization succeeds, the Klavi backend returns the redirectURL with the link_id and external_info parameters
If authorization fails, the Klavi backend returns the redirectURL with the link_id, external_info , error and error_description parameters
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.
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"
    }
}
﻿
Response
Name
Type
Required
Description
linkId
String
Yes
Unique identifier for the created link
linkToken
String
Yes
The token of the created link
You can think that the backend system will use accessToken(generated by /auth), while the front-end system will use this linkToken.
Only API GET /institutions and POST /consents will use this linkToken for authentication
linkURL
String
Yes
The Whitelabel application URL generated by Klavi for the partner, it can be opened as long as the partner's front-end requests this URL
expireIn
String
Yes
The expiration time of the linkToken, the default expiration duration is 30 minutes.
﻿

Name	Type	Required	Description
linkId	String	Yes	Unique identifier for the created link
linkToken	String	Yes	The token of the created link You can think that the backend system will use accessToken(generated by /auth), while the front-end system will use this linkToken. Only API GET /institutions and POST /consents will use this linkToken for authentication
linkURL	String	Yes	The Whitelabel application URL generated by Klavi for the partner, it can be opened as long as the partner's front-end requests this URL
expireIn	String	Yes	The expiration time of the linkToken, the default expiration duration is 30 minutes.

Refresh Access Token

Get Institution List