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:

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

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

Be careful

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

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

No API Key?

Check how to get one on authentication page.
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 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:

Use the Qualify Business Partner endpoint to send the below request,
Select one of the below examples,

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

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.

qualificationResultsqualificationDecisionSummaryqualificationDecisionDetails

Copy

Copied

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

Copy

Copied

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

Copy

Copied

{
      "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:

info

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 qualificationDecisionDetailsstructure 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 and Qualification Features sections.

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"
				}
			},
			"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 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"
				}
			},
			"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.

Copy

Copied

{
	"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!

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