---
title: Basic WhiteLabel
slug: connect/basic-whitelabel
docTags:
createdAt: 2023-11-24T06:20:00.666Z
---
# Introduction
The Basic Whitelabel is the integration method to use Klavi's services with the least development effort for your company.
Klavi will create one or more [partner applications](docId:4J4kP7KBvKq4C1pqpYU5z), each with its own set of configurations and a corresponding static whitelabel URL.
The Basic Whitelabel URL will provide to your end-user access to Klavi's whitelabel consent journey so you can start collecting data sharing consents.
# Obtain your Basic Whitelabel URLs
The whitelabel URLs for each app can be obtained through [Klavi Console](https://console.klavi.ai/), following the path below:
1. Login into your Console account
2. In the menu sidebar, select:
3. 'Integração'
4. 'Configurar endereços'
5. Select the desired environment
6. Copy the 'Basic Whitelabel URL' of the desired application
:::hint{type="warning"}
If you have any issues, contact Klavi through `suporte@klavi.ai`.
:::
## Basic Whitelabel URL Example
:::hint{type="info"}
Your Basic Whitelabel URL will follow the structure below:
[https://open-sandbox.klavi.ai/data/v1/basic-links/yourappid](https://open-sandbox.klavi.ai/data/v1/basic-links/yourappid)
:::
# How to use your Basic Whitelabel URLs
## Integration & Delivery
The Basic Whitelabel URL is ready-to-use and can be integrated into your application or sent to your end-users through messaging solutions. The URL can be opened using webview or directly in the device browser.
## Supported Path Parameters
The Basic Whitelabel URL supports path parameters, whose functions vary from data input automation (`personal_tax_id`, `phone`, `e-mail`), user redirection (`redirect_url`, `app_link`) and more.
:::hint{type="info"}
All supported path parameters must be used with `type = string`
:::
| **Parameter name** | **Description** |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **personal\_tax\_id ** | Automatically fills the user's CPF in the consent journey |
| **business\_tax\_id** | Automatically fills the business CNPJ in the consent journey |
| **email** | Automatically fills the user/business e-mail in the consent journey |
| **phone** | Automatically fills the user/business phone in the consent journey |
| **institution\_code** | Pre-determines the institution from which data will be shared. Skips institution selection page. |
| **redirect\_url** | The URL Klavi will redirect your end-user once the consent journey is completed.
It's value must be processed in `encodeURIComponent()` function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=” |
| **products\_callback\_url** | Set one or more product callback URLs. Has higher priority than the receival address configured in Klavi Console.
It's value must be processed in `encodeURIComponent()` function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=” |
| **external\_info** | Used for:
* Partners to transmit information, which will be carried in reports sent to partners.
* Customization of the consent journey UI, more details below.
It's value must be processed in `encodeURIComponent()` function as below, for example:
“%3a” replaces “:”
“%2f” replaces “/”
“%3f” replaces “?”
“%3d” replaces “=” |
| **app\_link** | Used when the partner wants to display the LGPD step inside their own app (via WebView). After the Open Finance authorization step is completed in the bank environment, the end-user is redirected to the URL provided in the
`app_link` parameter (typically a deep link or universal link of the partner’s app).
The redirect includes a query parameter whose name is defined by `app_redirect_url_key`. The value of this parameter is the Klavi-hosted LGPD URL, which the partner’s app must open in a WebView. |
| **app\_redirect\_url\_key** | Defines the name of the query parameter that Klavi will
add to the `app_link` URL. This parameter will contain the Klavi-hosted LGPD step URL as its value. The partner’s application must read this parameter and open its value inside a WebView. |
:::hint{type="warning"}
The above parameters are similar to the [Create a Link](docId\:vOrMoNRlpFxwuzDuIjl9t) API parameters, except for changing from a camelCase to snake\_case since Basic Whitelabel supports path parameters.
:::
::::ExpandableHeading
### Parameters Details
:::Heading{depth="3" indent="1"}
redirect\_url
:::
Since `redirect_url` must be filled with an URL, it is mandatory to [encode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) it:
```json
console.log(`?x=${encodeURIComponent('https://mydomain.com?uuid=22222')}`);
Output:
> "?x=https%3A%2F%2Fmydomain.com%3Fuuid%3D22222"
```
:::Heading{depth="3" indent="1"}
products\_callback\_url & external\_info
:::
`products_callback_url` and `external_info` are object type in the [/links](docId\:Mz5jyWMWVljrEZZqpd30s) API, If you want to use these parameters, remember to [stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) and [encode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) them:
```json
external_info=encodeURIComponent(JSON.stringify({ 'uuid': 'xxx-122-333-111','customization':{'institutions': [ '001', '033' ],'landingTitle': 'Welcome!','landingSubTitle': 'Welcome!'}}))
```
:::Heading{depth="3" indent="1"}
external\_info
:::
The `external_info` parameter has 2 different purposes:
1. Transmit relevant information to the partner: the data filled in this parameter will be included in corresponding [API Events](docId\:L2P6pW11AdwVumkNS6PKc) and [product reports](docId\:xkr8lrggFj7YFng1vaYdD) inside the externalInfo object.
2. Allow consent journey UI customization, using the `customization` key inside `external_info` object:
1. `institutions`: determines which institutions will be displayed in the institution selection list
2. `landingTitle`: determines the Landing Page title text
3. `landingSubtitle` determines the Landing Page subtitle text
:::CodeblockTabs
external\_info with customization object
```json
external_info = {'customization':
{'institutions': [ '001', '033' ],
'landingTitle': 'Welcome!',
'landingSubTitle': 'Welcome!'})
```
:::
:::Heading{depth="3" indent="1"}
app\_link & app\_redirect\_url\_key
:::
These parameters must be used together when the partner prefers to display the LGPD authorisation page inside his own application using Webview.
The `app_link` must be filled with the URL to which the end-user will be redirected to once the Open Finance authorisation in the bank environment is completed.
The `app_redirect_url_key` is a query parameter name defined by the partner. Its value will be the URL of the Klavi-hosted LGPD page. After the user is redirected to the `app_link`, the partner’s app must read this parameter and open its value in a WebView.
::::
# 2. Fetch Product Data
You can use web or webview to open the Link URL, make subsequent selection of institutions, redirect to that institution for authentication, and return to the final result web page.
Klavi backend will send you the results through event webhook(even if it is a failed state), after the status change to `AUTHORISED`, you can send the specific report generation request you want based on the end user type(personal or business, their endpoints are different).
Command:
```shell
curl --location 'https://api-sandbox.klavi.ai/data/personal/institution-data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer JhbGciOiJFUzI1NiIs.QtYjAyOC1hN2ZhMWFjZGRjZjkiLCJ0.nlTqpAZHeq4P2xFD' \
--data '{"taxId":"string","institutionId":"string","linkId":"String","consentId":"Array","products":"Array","productsCallbackURL":"Object"}'
```
Expected response:
```json
{
"requestId": "1325412e-e566-4f4e-ac5b-2f4471586b89",
"message": "ok"
}
```
After you submit a request to generate specific or all report(The report you want to purchase has already been limited by Klavi backend), Klavi randomly starts retrieving data from the institution and processing it to generate the corresponding report, which will be sent to you through the report webhook.
:::hint{type="info"}
Klavi also supports not having to actively call this endpoint. After you move to production, Klavi can proactively send all the reports to your webhook, or send them to Klavi's storage space. You can download them at any time through the [Klavi Console](https://console.klavi.ai).
:::