--- title: Create a Link slug: connect/create-a-link docTags: createdAt: 2023-11-21T07:26:39.314Z --- :::ApiMethodV2 ```json { "name": "links", "method": "POST", "url": "https://api-sandbox.klavi.ai/data/v1/links", "description": "Create a link by accessToken", "tab": "examples", "examples": { "languages": [ { "id": "sqUhPCBElt0jkpFkovLUY", "language": "curl", "code": "curl --location 'https://api-sandbox.klavi.ai/data/v1/links' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\"personalTaxId\":\"string\",\"businessTaxId\":\"string\",\"email\":\"string\",\"phone\":\"string\",\"institutionCode\":\"String\",\"redirectURL\":\"string\",\"productsCallbackURL\":\"Object\",\"externalInfo\":\"Object\",\"connectionKey\":\"string\"}'", "customLabel": "" } ], "selectedLanguageId": "sqUhPCBElt0jkpFkovLUY" }, "results": { "languages": [ { "id": "V0F3xDKIkgPjNb3Dy14d2", "language": "200", "code": "{\n \"linkId\": \"4437b139-8a16-11ee-b636-487b6bad036a\",\n \"linkURL\": \"https://open-sandbox.klavi.ai/path?v=AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD\",\n \"linkToken\": \"AhbGciOiJFUzI1NiIs.CtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.UlTqpAZHeq4P2xFD\",\n \"expireIn\": 1800\n}", "customLabel": "" } ], "selectedLanguageId": "V0F3xDKIkgPjNb3Dy14d2" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "Authorization", "kind": "required", "type": "string", "description": "Bearer access token, it returned by the /auth", "children": [] } ], "bodyDataParameters": [ { "name": "personalTaxId", "kind": "optional", "type": "string", "description": "The CPF of the end-user, for Personal Accounts only", "children": [] }, { "name": "businessTaxId", "kind": "optional", "type": "string", "description": "The CNPJ of the company, for Business Accounts only", "children": [] }, { "name": "email", "kind": "optional", "type": "string", "description": "End user's email, compliance needs", "children": [] }, { "name": "phone", "kind": "optional", "type": "string", "description": "End user's phone, compliance needs", "children": [] }, { "name": "institutionCode", "kind": "optional", "type": "String", "description": "Pre set parameters, the purpose is to avoid users choosing specific institutions", "children": [] }, { "name": "redirectURL", "kind": "optional", "type": "string", "description": "The URL for redirection upon successful link initialization", "children": [] }, { "name": "productsCallbackURL", "kind": "optional", "type": "Object", "description": "Report products callback URL, for Open finance only", "children": [] }, { "name": "externalInfo", "kind": "optional", "type": "Object", "description": "Used for partners to transmit information, which will be carried in reports sent to partners. \n", "children": [] }, { "name": "connectionKey", "kind": "optional", "type": "string", "description": "Connection key, the connectionKey has been sent to the partner in the report, for Open data update case only", "children": [] }, { "name": "appLink", "kind": "optional", "type": "string", "description": "After the institution authorization is completed, it will jump to this appLink with the appRedirectURLKey parameter", "children": [] }, { "name": "appRedirectURLKey", "kind": "optional", "type": "string", "description": "Partners can customize this parameter according to your actual situation.\nIf parameter appLink exists, this parameter must be exist.", "children": [] } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "response": [ { "name": "linkId", "kind": "optional", "type": "string", "description": "Unique identifier for the created link" }, { "name": "linkToken", "kind": "optional", "type": "string", "description": "The token of the created link\nYou can think that the backend system will use accessToken(generated by /auth), while the front-end system will use this linkToken.\nOnly API GET /institutions and POST /consents will use this linkToken for authentication", "children": [] }, { "name": "linkURL", "kind": "optional", "type": "string", "description": "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", "children": [] }, { "name": "expireIn", "kind": "optional", "type": "string", "description": "The expiration time of the linkToken, the default expiration duration is 30 minutes.", "children": [] } ], "hasTryItOut": false, "autoGeneratedAnchorSlug": "links", "legacyHash": "fNS849ea7VTwAiDpb-CqO" } ``` ::: ## 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" } } ``` 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" } } ``` 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" } } ``` After the report is generated, the Klavi backend will send all reports(You selected it when you onborading) to `https://www.yourdomain.com/yourpath`. :::hint{type="info"} 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", "customization": { "institutions": [ "001", "033" ], "landingTitle": "Welcome!", "landingSubTitle": "Welcome!" }, "transactionPeriod": 3 } } ``` :::hint{type="info"} - `customization`: the object can be used by partners to customize some content of whitelabel. For specific customized content, please contact the operations personnel ([suporte@klavi.ai](mailto\:suporte@klavi.ai)). - `transactionPeriod`: The number of complete periods covered by the provided transactions or statement data. For **checking accounts**, this represents the number of full calendar months spanned by the transactions. For **credit card accounts**, this represents the number of full billing cycles (statement periods) covered. The valid enumeration values are: \[**3, 6, 9**], if the partner does not pass this parameter, the default value is** 12**. it only valid for as follow `Institution-level` product: - PJ: - pj\_checking\_account - pj\_savings\_account - pj\_credit\_card - pj\_categorized\_checking\_L2 - pj\_categorized\_savings\_L2 - pj\_categorized\_creditcard\_L2 - pj\_categorized\_checking\_L3 - pj\_categorized\_savings\_L3 - pj\_categorized\_creditcard\_L3 - PF: - pf\_checking\_account - pf\_savings\_account - pf\_credit\_card - pf\_categorized\_checking\_L2 - pf\_categorized\_savings\_L2 - pf\_categorized\_creditcard\_L2 - pf\_categorized\_checking\_L3 - pf\_categorized\_savings\_L3 - pf\_categorized\_creditcard\_L3 :::