# Tutorial: How to update a Business Partner's attributes with qualification?

## Overview

**Use case**
This tutorial shows qualification as a mechanism for updating Business Partner information. For certain countries and data
sources, the appropriate values can be obtained by providing only the Business Partner identifier. In this case, the best
approach is to use `VIES` as a reference data source. Many methods exist for getting a Business Partner's attributes, and
this tutorial presents three of them.

Limitations
Some data sources have limitations in terms of qualifying Business Partners. See the [Current Limitations and Restrictions of CDQ's Qualification](#current-limitations-and-restrictions-of-cdqs-qualification)
section for more details.

Documentation
For more details check the endpoint's [documentation](https://developer.cdq.com/reference-docs/data-validation/V3/tag/Qualification/#tag/Qualification/paths/~1v3~1businesspartners~1qualify/post).

**Learning Goals**

In this tutorial, the user focuses on:

- Updating a Business Partner's attributes,
- Understanding the qualification results,
- Analyzing the qualification results.


## Prerequisites

### Authorization

Before trying CDQ APIs, user must be authenticated:

1. Paste the API Key in the console's security bar into the `X-API-KEY` field.


![](/assets/auth7.0d4fb05fa55bc16d828c76e9976f979930ffadb949cfc149a6617cc6518ab57d.6fde6558.png)

1. After pasting the API Key, the green padlock will appear.


![](/assets/auth8.28e02515b78db57ec32c07fd6bd7d296484e64f65ef6a3bc5296520cb1da8d65.6fde6558.png)

Be careful
Green padlock doesn't mean that the API Key was pasted correctly.

1. Check your API key for missing characters or extra space before trying.


#### No API Key?

1. Check how to get one on [authentication page](/documentation/instructions/authentication).
2. Follow the steps above.


### Qualification process

Before starting the qualification of the Business Partner, it's important to understand the qualification process well.
Check the [Qualification Process](/documentation/articles/processes/tax-guard-qualification-process) in CDQ Knowledge Base.

## Step 1: Update of a Business Partner's attributes

In this step, the user will update Business Partner attributes. One of the following examples can be selected:

| Example name | Description |
|  --- | --- |
| Update of a Business Partner based on Identifier and Fake Data | Getting the proper attributes such as name, postcode, locality, and thoroughfare of a Business Partner is based only on the EU VAT number. However, to get the correct values of various Business Partner attributes, it is necessary to send a valid identifier along with some arbitrary fake values of the attributes, represented as `X` in this case. |
| Update of a Business Partner based on Identifier Only | Only the identifier will be provided in the request, and all necessary values can be retrieved from the response's `value` field within the `externalServiceResponses/additionalInformation` structure. |
| Update of a Business Partner based on Lookup Results | A feature called `SHOW_LOOKUP_RESULTS` will be used in the context of the update mechanism. |


To update a Business Partner's attributes:

1. Use the **Qualify Business Partner** endpoint to send the below request,
2. Select one of the below examples,


1. Send the request.


Understanding the response structure described in [Step 2](#step-2-understand-the-qualification-results) is crucial to analyze
the qualification results. The response and appropriate comment are provided in [Step 3](#step-3-complete-response-to-analyze).

## Step 2: Understand the qualification results

### Response components explanation

The response from the qualification endpoint includes a new field called `qualificationResults`, which contains entries for
each identifier of a Business Partner based on the data sources it was checked against. Each `qualificationResults` entry
consists of two main components:

* the `qualificationDecisionSummary`, which provides an overview of the qualification decisions,
* the `qualificationDecisionDetails`, which presents the qualifications related to each target concept.


It's important to note that each element in the `qualificationResults` field represents results from only one data source.
Therefore, `qualificationResults` is structured as an array, where each element contains qualification decisions from a single
data source.


```json
{
    "qualificationResults": [
        {
            "identifier": { },
            "businessPartnerStatus": {},
            "qualifiedAt": "SOME_VALUE",
            "dataSourceTechnicalKey": "SOME_VALUE",
            "dataSourceRequestIdentifiers": [ ],
            "qualificationDecisionSummary": { },
            "qualificationDecisionDetails": [ ]
        }
    ],
    "debugInfo": { },
    "businessPartner": {},
    "lookupResults" : [],
    "rulesInError" : []
}
```


```json
{
    "qualificationDecisionSummary": {
        "identifierQualificationDecision": "SOME_VALUE",
        "nameQualificationDecision": "SOME_VALUE",
        "addressQualificationDecision": "SOME_VALUE",
        "addressQualificationDecisionDetails": {
            "localityQualificationDecision": "SOME_VALUE",
            "postCodeQualificationDecision": "SOME_VALUE",
            "thoroughfareQualificationDecision": "SOME_VALUE"
        },
        "overallQualificationDecision": "SOME_VALUE"
    }
}
```


```json
{
      "qualificationDecisionDetails": [
          {
              "businessRule": {
                  "name": "SOME_VALUE",
                  "url": "SOME_VALUE",
                  "ruleStatus": "SOME_VALUE",
                  "violationMessage": "SOME_VALUE"
              },
              "executionContextProperties": [
                  {
                      "name": "qualificationTarget",
                      "value": "SOME_VALUE"
                  },
                  {
                      "name": "targetInputValue",
                      "value": "SOME_VALUE"
                  },
                  {
                      "name": "targetReferenceValue",
                      "value": "SOME_VALUE"
                  },
                  {
                      "name": "dataSourceTechnicalKey",
                      "value": "SOME_VALUE"
                  },
                  {
                      "name": "dataSourceRequestIdentifier",
                      "value": "SOME_VALUE"
                  }
              ],
              "cdqId": "SOME_VALUE",
              "decision": "SOME_VALUE",
              "error": {}
          }
      ]
}
```

A response from the `/businesspartners/qualify` endpoint follows a specific structure as detailed in the qualification response
example preceding. Within this structure, `SOME_VALUE` can denote various types of elements, including:

* identifier,
* name,
* date and time,
* decision,
* other values.


Generally, a `key`, such as `qualifiedAt` or `dataSourceRequestIdentifiers`, is placed before the value, providing insights
into the expected content.

**Detailed response structure explanation**:

The `qualificationResults` top structure includes the following elements:

| **Property Name** | **Description** |
|  --- | --- |
| **identifier** | The value and type of an identifier. |
| **businessPartnerStatus** | The status of a business partner if provided by a reference data source (it might be unknown). |
| **qualifiedAt** | The timestamp when the check was performed. |
| **dataSourceTechnicalKey** | The data source that was queried. |
| **dataSourceRequestIdentifier** | For the `VIES` data source, this field provides a request identifier confirming that a request has been sent; this feature requires the `FORCE_EXTERNAL_CALL` setting to be enabled. |
| **qualificationDecisionSummary** | A summary of the qualification decisions. |
| **qualificationDecisionDetails** | Detailed information about each decision obtained. |
| **executionContextProperties** | A set of execution context properties represented as `"name": "value"` pairs. Currently, the following property names are available: |


The `qualificationDecisionSummary`, `qualificationDecisionDetails` and `executionContextProperties` details are listed below.

The `qualificationDecisionSummary` top structure includes the following elements:

| **Property Name** | **Description** |
|  --- | --- |
| **identifierQualificationDecision** | Decision regarding the provided identifier. |
| **nameQualificationDecision** | Decision about the Business Partner's name. |
| **addressQualificationDecision** | Decision based on the provided address fields, calculated using decisions about postcode, locality, and thoroughfare. |
| **addressQualificationDecisionDetails** | Detailed information about address decisions, which includes: `localityQualificationDecision`, `postCodeQualificationDecision`, and `thoroughfareQualificationDecision`. |
| **overallQualificationDecision** | The overall decision, determined by the following hierarchy: `NOT_PROCESSED` < `NO_INPUT_PROVIDED` < `VALID` < `NO_REFERENCE_AVAILABLE` < `INVALID` < `EXECUTION_ERROR`. This hierarchy represents the highest decision based on the previous decisions about the identifier, name, locality, postcode, and thoroughfare. |


The `qualificationDecisionDetails`structure includes the following elements:

- **`businessRule`**: The specific rule that led to a decision.


| **Property Name** | **Description** |
|  --- | --- |
| **name** | The name of the rule. |
| **url** | The rule's URL on our Wiki. |
| **ruleStatus** | The current status of the rule: `HYPERCARE` or `RELEASED`. |
| **violationMessage** | A message detailing any violations related to defective data. |


The `executionContextProperties` structure includes the following elements:

| **Property Name** | **Description** |
|  --- | --- |
| **qualificationTarget** | The target type being qualified, with possible values of `IDENTIFIER`, `NAME_LOCAL`, `CITY`, `STREET`, and `POST_CODE_REGULAR`. |
| **targetInputValue** | The value provided by a user. |
| **targetReferenceValue** | The value returned by a reference data source (e.g., `VIES`). |
| **dataSourceTechnicalKey** | The queried data source (e.g., `VIES`, `BZST`, `AT.FON`). |
| **dataSourceRequestIdentifier** | The request identifier provided by `VIES`. |


- `cdqId` - The `CDQ ID` value, if it exists, which uniquely identifies the data source and identifier for a Business Partner.
- `decision` - The current decision returned by the rule.
- `error` - If the check fails, an appropriate error message is provided, including an optional ID value. If applicable, the `rulesInError` object will contain a list of failed rules.


The qualification response may also include a `debugInfo` structure, which provides additional details about the qualification
process. This includes statistics on executed and failed rules, categories of rules considered, and activated data sources.
Additionally, if available, it provides a raw response from external data sources. To access the `debugInfo` data, users
must enable specific feature. More information about potential structures that the `/qualify` endpoint may return can be
found in the [Qualifications Profiles](/documentation/articles/processes/tax-guard-qualification-process/#qualification-profiles) and [Qualification Features](/documentation/articles/processes/tax-guard-qualification-process/#qualification-features) sections.

## Step 3: Complete response to analyze

Depending on the selected example in [Step 1](#step-1-update-of-a-business-partners-attributes), scroll down and find matching response. It will contain the qualification results for the Business Partner. Chose one
of the below cases to see the response:

### Update of a Business Partner based on Identifier and Fake Data

The response indicates a `VALID` decision for the identifier, while other decisions are `INVALID`, which corresponds to the
incorrect value set in the request. The field `targetReferenceValue` in the `executionContextProperties` structure for each
executed rule reveals important information. This allows for an assumption that the company's name is `SAS DB COMPANY` and
its postcode is `59100`, among other details.


```json
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"businessPartnerStatus": {
				"type": {
					"name": "Unknown",
					"url": "https://meta.cdq.com/Business_partner/status/type/technical_key/unknown",
					"technicalKey": "UNKNOWN"
				}
			}, 
			"qualifiedAt": "2024-08-29T16:36:32.803550067",
			"dataSourceTechnicalKey": "VIES",
			"dataSourceRequestIdentifiers": [
				{
					"dataSourceTechnicalKey": "VIES",
					"value": "WAPIAAAAZGe_uwXb"
				}
			],
			"qualificationDecisionSummary": {
				"identifierQualificationDecision": "VALID",
				"nameQualificationDecision": "INVALID",
				"addressQualificationDecision": "INVALID",
				"addressQualificationDecisionDetails": {
					"localityQualificationDecision": "INVALID",
					"postCodeQualificationDecision": "INVALID",
					"thoroughfareQualificationDecision": "INVALID"
				},
				"overallQualificationDecision": "INVALID"
			},
			"qualificationDecisionDetails": [
				{
					"businessRule": {
						"name": "Thoroughfare Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Thoroughfare_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Street deviates from the reference street registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "STREET"
						},
						{
							"name": "targetInputValue",
							"value": "X"
						},
						{
							"name": "targetReferenceValue",
							"value": "Rue De Tourcoing"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_uwXb"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "INVALID"
				},
				{
					"businessRule": {
						"name": "Post code Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Post_code_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Post code deviates from the reference post code registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "POST_CODE_REGULAR"
						},
						{
							"name": "targetInputValue",
							"value": "X"
						},
						{
							"name": "targetReferenceValue",
							"value": "59100"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_uwXb"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "INVALID"
				},
				{
					"businessRule": {
						"name": "Name Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Name_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Name deviates from the reference name registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "NAME_LOCAL"
						},
						{
							"name": "targetInputValue",
							"value": "X"
						},
						{
							"name": "targetReferenceValue",
							"value": "SAS DB COMPANY"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_uwXb"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "INVALID"
				},
				{
					"businessRule": {
						"name": "Locality Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Locality_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "City deviates from the reference city registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "CITY"
						},
						{
							"name": "targetInputValue",
							"value": "X"
						},
						{
							"name": "targetReferenceValue",
							"value": "Roubaix"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_uwXb"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "INVALID"
				},
				{
					"businessRule": {
						"name": "Identifier Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Identifier_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Identifier deviates from the reference identifier registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "IDENTIFIER"
						},
						{
							"name": "targetInputValue",
							"value": "FR35852293547"
						},
						{
							"name": "targetReferenceValue",
							"value": "FR35852293547"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_uwXb"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-08-29T16:36:32.719561083Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_uwXb"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_uwXb\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			},
			{
				"status": 200,
				"timestamp": "2024-08-29T16:36:32.719561083Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_uwXb"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_uwXb\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			},
			{
				"status": 200,
				"timestamp": "2024-08-29T16:36:32.719561083Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_uwXb"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_uwXb\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			},
			{
				"status": 200,
				"timestamp": "2024-08-29T16:36:32.719561083Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_uwXb"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_uwXb\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			},
			{
				"status": 200,
				"timestamp": "2024-08-29T16:36:32.719561083Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_uwXb"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_uwXb\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			}
		],
		"businessRulesExecutionSummary": {
			"numberOfRules": 5,
			"numberOfExecutions": 5,
			"numberOfFails": 0,
			"failures": [],
			"dataSourcesOn": [
				{
					"prefix": "VIES"
				},
				{
					"prefix": "AT.FON"
				}
			],
			"ruleCategoriesOn": [
				{
					"url": "https://meta.cdq.com/EU_TAX_Qualification"
				}
			]
		}
	}
}
```

### Update of a Business Partner based on Identifier Only

A `VALID` decision is received for the identifier, while a `NO_INPUT_PROVIDED` decision is given for the remaining attributes,
as they weren't included in the request. A direct raw response from the reference data source, `VIES` in this case, is also
got, along with additional CDQ attributes from `referenceAddressDto`, allowing for easy extraction of appropriate values
for the Business Partner's attributes. It's important to note that this raw response from the external data source was
present in the [previous](#update-of-a-business-partner-based-on-identifier-and-fake-data) use case. Additionally, if this approach is used, it's necessary to implement parsing for
various raw responses, as each external data source has its own unique format and structure.


```json
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"businessPartnerStatus": {
				"type": {
					"name": "Unknown",
					"url": "https://meta.cdq.com/Business_partner/status/type/technical_key/unknown",
					"technicalKey": "UNKNOWN"
				}
			}, 
			"qualifiedAt": "2024-08-29T16:37:27.308368549",
			"dataSourceTechnicalKey": "VIES",
			"dataSourceRequestIdentifiers": [
				{
					"dataSourceTechnicalKey": "VIES",
					"value": "WAPIAAAAZGe_8F6b"
				}
			],
			"qualificationDecisionSummary": {
				"identifierQualificationDecision": "VALID",
				"nameQualificationDecision": "NO_INPUT_PROVIDED",
				"addressQualificationDecision": "NO_INPUT_PROVIDED",
				"addressQualificationDecisionDetails": {
					"localityQualificationDecision": "NO_INPUT_PROVIDED",
					"postCodeQualificationDecision": "NO_INPUT_PROVIDED",
					"thoroughfareQualificationDecision": "NO_INPUT_PROVIDED"
				},
				"overallQualificationDecision": "VALID"
			},
			"qualificationDecisionDetails": [
				{
					"businessRule": {
						"name": "Identifier Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Identifier_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Identifier deviates from the reference identifier registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "IDENTIFIER"
						},
						{
							"name": "targetInputValue",
							"value": "FR35852293547"
						},
						{
							"name": "targetReferenceValue",
							"value": "FR35852293547"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGe_8F6b"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-08-29T16:37:27.265705232Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGe_8F6b"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGe_8F6b\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			}
		],
		"businessRulesExecutionSummary": {
			"numberOfRules": 1,
			"numberOfExecutions": 1,
			"numberOfFails": 0,
			"failures": [],
			"dataSourcesOn": [
				{
					"prefix": "VIES"
				},
				{
					"prefix": "AT.FON"
				}
			],
			"ruleCategoriesOn": [
				{
					"url": "https://meta.cdq.com/EU_TAX_Qualification"
				}
			]
		}
	}
}
```

### Update of a Business Partner based on Lookup Results

The appropriate response returns lookup results with all attributes of a Business Partner. It's important to note that the
usage of the qualification for Business Partner enrichment has some limitations. Mainly, there are restrictions from `VIES`
for Spanish and German Business Partners and `BZST` for all supported countries. In those cases both data sources don't provide reference
values that could be used for enrichment; they only provide proper decisions, like `VALID` or `INVALID`. In general, `VIES`
is the best data source to use in cases of data enrichment, except for Spain and Germany. For enriching German or Spanish
Business Partners, the best approach is to use `AT.FON` as a reference data source.


```json
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"businessPartnerStatus": {
				"type": {
					"name": "Unknown",
					"url": "https://meta.cdq.com/Business_partner/status/type/technical_key/unknown",
					"technicalKey": "UNKNOWN"
				}
			}, 
			"qualifiedAt": "2024-08-29T16:39:22.993133113",
			"dataSourceTechnicalKey": "VIES",
			"dataSourceRequestIdentifiers": [
				{
					"dataSourceTechnicalKey": "VIES",
					"value": "WAPIAAAAZGfAYVFc"
				}
			],
			"qualificationDecisionSummary": {
				"identifierQualificationDecision": "VALID",
				"nameQualificationDecision": "NO_INPUT_PROVIDED",
				"addressQualificationDecision": "NO_INPUT_PROVIDED",
				"addressQualificationDecisionDetails": {
					"localityQualificationDecision": "NO_INPUT_PROVIDED",
					"postCodeQualificationDecision": "NO_INPUT_PROVIDED",
					"thoroughfareQualificationDecision": "NO_INPUT_PROVIDED"
				},
				"overallQualificationDecision": "VALID"
			},
			"qualificationDecisionDetails": [
				{
					"businessRule": {
						"name": "Identifier Qualification (European value added tax identifier (France), Data source:VIES)",
						"url": "https://meta.cdq.com/Identifier_Qualification_(European_value_added_tax_identifier_(France),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Identifier deviates from the reference identifier registered with the European value added tax identifier (France)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "IDENTIFIER"
						},
						{
							"name": "targetInputValue",
							"value": "FR35852293547"
						},
						{
							"name": "targetReferenceValue",
							"value": "FR35852293547"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZGfAYVFc"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [
		{
			"businessPartner": {
				"externalId": "FR35852293547",
				"addresses": [
					{
						"version": {
							"characterSet": {
								"technicalKey": "LATIN"
							},
							"language": {
								"name": "en",
								"technicalKey": "en"
							}
						},
						"country": {
							"shortName": "FR",
							"value": "France"
						},
						"administrativeAreas": [],
						"postCodes": [
							{
								"value": "59100",
								"type": {
									"name": "Regular",
									"url": "https://meta.cdq.com/Address/post_code/type/regular",
									"technicalKey": "REGULAR"
								}
							}
						],
						"localities": [
							{
								"value": "Roubaix",
								"type": {
									"name": "City",
									"url": "https://meta.cdq.com/Address/locality/type/city",
									"technicalKey": "CITY"
								},
								"shortName": "Roubaix"
							}
						],
						"thoroughfares": [
							{
								"type": {
									"name": "Street",
									"url": "https://meta.cdq.com/Address/thoroughfare/type/street",
									"technicalKey": "STREET"
								},
								"shortName": "Rue De Tourcoing",
								"number": "89",
								"value": "Rue De Tourcoing"
							}
						],
						"premises": [],
						"postalDeliveryPoints": []
					}
				],
				"names": [
					{
						"type": {
							"url": "https://meta.cdq.com/Business_partner/name/type/vat_registered_name",
							"name": "VAT Registered Name",
							"technicalKey": "VAT_REGISTERED"
						},
						"value": "SAS DB COMPANY"
					}
				],
				"identifiers": [
					{
						"value": "FR35852293547",
						"type": {
							"url": "https://meta.cdq.com/European_value_added_tax_identifier_(France)",
							"name": "Value added tax identification number",
							"technicalKey": "EU_VAT_ID_FR"
						}
					}
				],
				"legalForm": {
					"name": "Société par actions simplifiée",
					"mainAbbreviation": "SAS",
					"url": "https://meta.cdq.com/Business_partner/legal_form/technical_key/FR_1687",
					"technicalKey": "FR_1687"
				}
			},
			"dataSource": "VIES",
			"cdqId": "VIES:FR35852293547"
		}
	],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-08-29T16:39:22.955707328Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGfAYVFc"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-08-28T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"FR\"},\"valid\":{\"value\":true},\"traderAddress\":{\"value\":\"89 RUE DE TOURCOING\\n59100 ROUBAIX\"},\"traderName\":{\"value\":\"SAS DB COMPANY\"},\"traderCompanyType\":{\"value\":\"---\"},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZGfAYVFc\"},\"referenceAddressDto\":{\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}},\"metadata\":{},\"country\":{\"shortName\":\"FR\",\"value\":\"France\"},\"postCodes\":[{\"value\":\"59100\"}],\"localities\":[{\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"},\"shortName\":\"Roubaix\",\"value\":\"Roubaix\"}],\"thoroughfares\":[{\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"},\"shortName\":\"Rue De Tourcoing\",\"number\":\"89\",\"value\":\"Rue De Tourcoing\",\"name\":\"RUE DE TOURCOING\"}]},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			}
		],
		"businessRulesExecutionSummary": {
			"numberOfRules": 1,
			"numberOfExecutions": 1,
			"numberOfFails": 0,
			"failures": [],
			"dataSourcesOn": [
				{
					"prefix": "VIES"
				},
				{
					"prefix": "AT.FON"
				}
			],
			"ruleCategoriesOn": [
				{
					"url": "https://meta.cdq.com/EU_TAX_Qualification"
				}
			]
		}
	}
}
```

## 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!