# How to qualify Business Partner using First Time Right app?

## Overview

**Use Case**

Qualifying Business Partners can be achieved using the First Time Right (FTR) app, which includes a new Tax Guard capability
accessible through the Qualify button. Additionally, it covers how to take advantage of the appropriate settings and manage
the Tax Guard Qualification results displayed in FTR. The Qualify button utilizes the `/businesspartners/qualify` endpoint,
operable through Data Validation API version 3.

To understand better the qualification process, get familiar with:

* [Tax Guard Qualification Process](/documentation/articles/processes/tax-guard-qualification-process/).
* CDQ Tax Guard tutorials section on the [Tutorial Page](/documentation/tutorials/tutorials-landing-page/).


## Prerequisites

**Login**

Log into the CDQ [Cloud Apps](https://apps.cdq.com).

Authorization
If you have no access to the CDQ Cloud App, ask internal point of contact to create a CDQ dedicated account.
Account details will be sent by email.

## Step 1: How to set the qualification profiles and features?

The **Tax Guard Qualification** provides two profiles, four features and eighteen different data sources. All of them are
available in the FTR app settings.

Read the [Tax Guard Qualification Process](https://developer.cdq.com/documentation/articles/processes/tax-guard-qualification-process/) for more details.

To set the qualification profiles and features:

1) Navigate to [First Time Right](https://apps.cdq.com/dashboard/first-time-right) app,


![](/assets/img-ftr1-000.b05436ff28248fcf14b0ae4118636f23e0e191640b56b83e663a395dc8703bd9.cbb72118.png)

1) Click on the **Settings** icon in the top right corner,
2) Check the **Qualification** tab.


![](/assets/img-ftr1-001.bd37a01336e44f97c943d2652076a682481fb8cd828142faab3641511b05024f.cbb72118.png)

In the setting window user can set the qualification profiles and features:

* **Profile**: Select `EU TAX QUALIFICATION` or `WORLDWIDE TAX QUALIFICATION`.
* **Data source**: One or more of the available data sources. Use **Select All** option, to add all available data sources.
* **Features On**: Features to be turned on during qualification.
* **Features Off**: Features to be turned off during qualification.


The same features can't be set as On and Off at the same time. Moreover, it isn't allowed in the Tax Guard Qualification Configuration view.

br
![](/assets/img-ftr1-002.7330dedb5b5ee64c0652294859a4e3520bbc68e592282f7ad71b2f485c43401a.cbb72118.png)

The default configuration for Tax Guard Qualification includes `EU TAX QUALIFICATION` profile with `SHOW DEBUG INFO` feature set to On.

All the Tax Guard Qualification settings are described in the [Tax Guard Qualification Process](https://developer.cdq.com/documentation/knowledge-base/processes/tax-guard-qualification-process/).

## Step 2: Understanding the qualification results in FTR app

The qualification results are displayed in the FTR app after clicking the **Qualify** button. To see the results, follow these steps:

1) Set the qualification profiles and features in the **Settings** view:
  * **Profile**: `EU TAX QUALIFICATION`
  * **Data source**: `VIES`
  * **Features On**: `SHOW DEBUG INFO`
2) Save changes,
3) Set the values to qualify the Business Partner:
  * **Country**: `PL - Poland`
  * **Identifier**: `PL8992790965`
  * **Type**: `EU_VAT_ID_PL`
4) Click the **Qualify** button,
5) Analyze the qualification results.


![](/assets/img-ftr1-003.0f9dde703f583da2a4a1776636e3436a5167eccef8252f98dede3abdda1acb61.cbb72118.png)

### Analyzis

**Two orders of decisions**

Two different views of the overall qualification decision are available: 

![](/assets/img-ftr1-005.aabbc0f5530ca34087a33459321274d5f6944287f4d2b51a36a6d40331354c89.cbb72118.png)

- **Reliability** - This reflects the importance of statuses from a `VALID`/`INVALID` perspective. In this case, these two decisions are the most significant and are presented at the beginning of all other decisions.
- **Hierarchy** - This indicates the order of decisions that the Tax Guard Qualification provides. Based on the detailed decisions, the overall decision is calculated.


**Get the Request identifier**

If the `FORCE EXTERNAL CALL` feature is enabled for `VIES`, the results provide a request identifier, such as `WAPIAAAAZPepAheS`. 

![](/assets/img-ftr1-006.bbf593489739593e6e653d3903899bc699ca908f53700d8c7c827871fa7d7254.cbb72118.png)

**Get the Business Partner Status**

If the Business Partner Status value differs from `ACTIVE` or `UNKNOWN`, it will be displayed under **Overall qualification decision**
and under **VIES Request Identifier** if present. See an example of qualification results in the case of an `INACTIVE` Business Partner: 

![](/assets/img-ftr1-0017.dc900f08fdc0d677492ab15ebd1aecb125c395206909beb75b57a85f458965f2.cbb72118.png)

**Detailed decisions**

Detailed decisions include:

- decision type,
- input value ,
- qualification decision,
- reference value (if possible), and
- a business rule that provided the decision.


Clicking on a decision allows accessing the violation message, discover the rule's name, and conveniently visit the CDQ Wiki for more information on that rule.

![](/assets/img-ftr1-004.059bd1de59ae511fa7d19b9648ccec50690b4e560e5d4a14dca338592e7d9846.cbb72118.png)

Check the [Tax Guard Qualification Process](/documentation/articles/processes/tax-guard-qualification-process#qualification-decisions) for decision statuses explanation.

Each decision is color-coded to simplify the understanding of qualification results.

| Decision | Description |
|  --- | --- |
| Valid | The input value and the reference value provided by the qualification data source are judged as congruent. |
| Invalid | There is no congruency between the input value and the reference value provided by the qualification data source. |
| Not_Processed | There is no rule for qualifying this particular target, a rule was deactivated, or we are not able to process this particular data field. |
| No_Input_Provided | There was no input value provided. So, there is no possible comparison with the reference value provided by the qualification data source. |
| No_Reference_Available | the qualification data source provided no reference value. So, there is no comparison possible. This might happen when no such a value is available or the mapping and transformation of the raw data source are not working correctly, resulting in an empty value. Anyway, such cases need to be checked by a user. |
| Execution_Error | A rule was not properly executed, e.g., there was some internal software issue, or a qualification data source was not available (downtimes, connection lags, etc.). |


**Errors**

An explanation is provided in situations where errors occur, for example:

- the data source isn't available,
- the maximum number of requests per day for a specific identifier is exceeded.


![](/assets/img-ftr1-008.2a64a27c18103fe2d7158f4872a3dd11b7ccb211e6439a927bed199a53ffe1bb.cbb72118.png)

**Info Icon**

A special info icon is provided ![](/assets/infoicon.041f027b25ea7049689a44c651cfc87f0d10b3a74d862d578e4ca64905cd199a.cbb72118.png). When clicked, it describes a particular element, allowing for quick explanations.

## Step 3: Qualify the Business Partner in FTR app

For better understanding, analyze those three cases of qualifying Business Partners. All cases are qualified in FTR app with different settings. Detailed data like identifier comes from the **Lookup** results but can be changed or provided manually.

Remember that the user must provide values like country, identifier type, and identifier itself to perform a qualification process. In some cases, like when using `BZST`, additional fields, such as name and city, need to be given.

In the following examples, the following data is used:

* **Name**: `CDQ`
* **Country**: `PL - Poland`


### Qualify European Business Partner with Default Settings

To qualify a European Business Partner with default settings, follow these steps:

1) Set the qualification profiles and features in the **Settings** view:
  * **Profile**: `EU TAX QUALIFICATION`,
  * **Features On**: `SHOW DEBUG INFO`,
2) Fill the provided values:
  * **Name**: `CDQ`,
  * **Country**: `PL - Poland`,
3) Click the **Lookup** button,


![](/assets/img-ftr1-009.953ae623f11e053e55f0b61edb228d94d5f536880036d9de2c9fb551a8c3e75d.cbb72118.png) 

1) Select the results from the `VIES` data source,
2) Click the `Transfer values to search mask` button,


![](/assets/img-ftr1-0010.fbfc488f36e0557121680b6b97f83df0c72831bfc8155bcd9a00005366274619.cbb72118.png) 

1) When the values are transferred, click the **Qualify** button,
2) Analyze the qualification results.


![](/assets/img-ftr1-0011.3fdecd1484f2d991f088defa63b8b67224d8a1e1f7b1d9ed026ff4c219c6ea38.cbb72118.png) 

Only valid decisions were obtained, which are consistent with what `VIES` provides.

### Qualify European Business Partner with Multiple Data Sources

To qualify a European Business Partner with multiple data sources, follow these steps:

1) Set the qualification profiles and features in the **Settings** view:
  * **Profile**: `EU TAX QUALIFICATION`,
  * **Data source**: `VIES`, `BZST`, `AT.FON`,
  * **Features On**: `FORCE EXTERNAL CALL`,
2) Fill the provided values:
  * **Name**: `CDQ`,
  * **Country**: `PL - Poland`,
3) Click the **Lookup** button,
4) Select the results from the `VIES` data source,
5) Click the `Transfer values to search mask` button,
6) When the values are transferred, click the **Qualify** button,
7) Check the results from other data sources by switching the pages.


![](/assets/img-ftr1-0012.9beeb58e55b8996106c448f4153ad117d661ea043bab2a94ca0dff2482dce7c7.cbb72118.png) 

![](/assets/img-ftr1-0013.e208b7d5eca2e3fd6d5fb2272589caa222a5431272ffe570e6f2eaa899381c99.cbb72118.png) 

### Qualify European Business Partner with European and Local Registers

To qualify a European Business Partner with European and Local Registers, follow these steps:

1) Set the qualification profiles and features in the **Settings** view:
  * **Profile**: `EU TAX QUALIFICATION`,
  * **Data source**: `VIES`, `PL.NOBR`,
  * **Features On**: `FORCE EXTERNAL CALL`,
2) Fill the provided values:
  * **Name**: `CDQ`,
  * **Country**: `PL - Poland`,
3) Click the **Lookup** button,
4) Select the `Golden Record`,
5) Click the `Transfer values to search mask` button,


![](/assets/img-ftr1-0014.21099564dbcc9713c66e97c5bde2490aaabccf1a5babe50604be2fa37fb168af.cbb72118.png)

1) When the values are transferred, click the **Qualify** button,
2) Analyze the qualification results,
3) Check the results from `VIES` for identifier type `PL_REG`.


![](/assets/img-ftr1-0015.510b2df9210f88697c4242fc7510e76e1b4b93cede3d96df89c3ab7246801c78.cbb72118.png)

1) Check the results from `PL.NOBR` for identifier type `PL_REG`.


![](/assets/img-ftr1-0016.13aae547a87f7a8ceb097b2a533a45036af9c98244420509c6164559782cdef0.cbb72118.png)

The `PL_REG` identifier type exist in the `PL.NOBR` data source and is `VALID` in the decision column. It doesn't exist in the `VIES` data source, and it's why it has `NOT PROCESSED` decision.

## Current Limitations and Restrictions of CDQ's Qualification

The `/businesspartners/qualify` endpoint enables the use of 18 different data sources. Not all data sources behave the same
way or provide results in the same format. To integrate all of them, the necessary steps were taken to follow each data
source's restrictions. A common interface has been provided with the following limitations:

| Limitations |
|  --- |
| `BZST` does not support German Business Partners. |
| `VIES` can validate only the EU VAT identifier of German Business Partners but does not provide reference data for the German address and name. |
| `VIES` does not return reference data for Spanish Business Partners; it merely indicates whether a given input, such as name and address, is a match. |
| Currently, only `AT.FON` can fully qualify German Business Partners with all attributes: identifier, postcode, name, locality, and thoroughfare. |
| If the `dataSources` attribute is included in a request, results for each identifier from each requested data source will be provided, which may lead to many `NOT_PROCESSED` decisions. |
| In some cases, qualification of an identifier is based on the calculation of other checked fields: postcode, name, locality, and thoroughfare due to the absence of specific rules for checking the identifier alone; this remains under active development. |
| Qualification can fail if issues arise with connecting to a reference data source, such as if it is undergoing maintenance. All issues that occur during execution will be available in the `debugInfo` data field of a response. |
| Currently, it is possible to qualify five data fields: identifier, postcode, name, locality, and thoroughfare of a Business Partner. If other Business Partner attributes require qualification, customers are encouraged to create an idea in the idea portal. |
| Values that are empty or missing fields, such as not present `"postCodes": []` data, result in the `NO_INPUT_PROVIDED` decision. |
| Not all data sources provide the status of a business partner. For example, `VIES` provides decisions about the validity of an identifier but does not provide anything about the business partner status itself. As a result we usually provide status `UNKNOWN` except in cases when a reference data source provides otherwise (like in the `CZ.REE` register). |


## Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!