Create a Link

8min

Create a link by accessToken
POST
Request
Header Parameters
Authorization
required
String
Bearer access token, it returned by the /auth
Body Parameters
personalTaxId
optional
String
The CPF of the end-user, for Personal Accounts only
businessTaxId
optional
String
The CNPJ of the company, for Business Accounts only
email
optional
String
End user's email, compliance needs
phone
optional
String
End user's phone, compliance needs
institutionCode
optional
String
Pre set parameters, the purpose is to avoid users choosing specific institutions
redirectURL
optional
String
The URL for redirection upon successful link initialization
productsCallbackURL
optional
Object
Report products callback URL, for Open finance only
externalInfo
optional
Object
Used for partners to transmit information, which will be carried in reports sent to partners. 
connectionKey
optional
String
Connection key, the connectionKey has been sent to the partner in the report, for Open data update case only
applicationLink
optional
String
After the institution authorization is completed, it will jump to the applicationLink address with the link_callback_url parameter (only useful when using WhiteLabel)
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.

Updated 21 Nov 2024

Did this page help you?

Refresh Access Token

Get Institution List