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 section for more details.

Documentation

For more details check the endpoint's documentation.

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.
auth7
  1. After pasting the API Key, the green padlock will appear.
auth8
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.
  2. Follow the steps above.

Qualification process

info

Before starting the qualification of the Business Partner, it's important to understand the qualification process well. Check the 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 nameDescription
Update of a Business Partner based on Identifier and Fake DataGetting 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 OnlyOnly 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 ResultsA 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,
Loading...
  1. Send the request.
info

Understanding the response structure described in Step 2 is crucial to analyze the qualification results. The response and appropriate comment are provided in Step 3.

Step 2: Understand the qualification results

Response components explanation

Step 3: Complete response to analyze

Depending on the selected example in Step 1, 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.
Copy
Copied
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"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 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.
Copy
Copied
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"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.
Copy
Copied
{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"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.

Your opinion matters!

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

Mail our developer-portal team: developer-portal@cdq.com