Tutorial: How to qualify a Business Partner with identifiers?

Overview

Use case

This tutorial focuses on qualifying EU VAT identifiers only. It might be helpful to check if a given EU VAT number, associated with a business partner, is permitted for cross-border transactions within the European Union. In this case, using VIES as a reference data source is the best approach.

Documentation

For more details check the endpoint's documentation.

Learning Goals

In this tutorial, the user focuses on:

Qualifying a Business Partner using identifiers,
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.

Step 1: Qualification of a Business Partner with identifiers

In this step, the user will qualify a Business Partner using local registers. The user can select one of the following examples:

Example name	Description
Qualification of a French Business Partner's Identifier Only	This example involves qualifying the EU VAT identifier of a French business partner. To qualify an identifier, only the type of the given identifier and the identifier itself need to be provided.
Qualification of a German Business Partner's Identifier Only Using `AT.FON`	This example focuses on qualifying the EU VAT identifier of a German business partner. By default, `AT.FON` is applied because this is the only reference data source that can fully qualify German business partners.
Qualification of a German Business Partner's Identifier Only Using `VIES`	This example qualifies the EU VAT identifier of a German business partner using `VIES` as a reference data source. Fortunately, `VIES` can qualify EU VAT identifiers of German business partners, but only this attribute. No other attribute, such as post code or name, can be qualified using `VIES`.

To qualify a Business Partner with local registers:

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": { },
            "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.
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 a Business Partner. Chose one of the below cases to see the response:

Qualification of a French Business Partner's Identifier Only

The response clearly indicates that the identifier qualification decision is VALID, confirming that the EU_VAT_ID_FR is correct. Other decisions reflect NO_INPUT_PROVIDED, indicating that no additional business partner attributes were supplied in the request. Furthermore, within the qualificationDecisionDetails structure, it can be seen that only one rule was executed, with its execution context properties presented as name and value pairs. Additionally, the set of properties includes a confirmation from VIES, indicating that the request was processed and the decision was VALID. This information can be found under the dataSourceRequestIdentifier execution context property, which in this scenario is WAPIAAAAZGy74Ftg. It's important to note that this request identifier will only appear when FORCE_EXTERNAL_CALL is set, ensuring that the external reference data source is accessed during qualification. If a failure occurs, local CDQ storage will be used if possible, and in such cases, the request identifier from VIES won't be included in the response.

The overall decision is determined using a hierarchy that ranks as follows:

NOT_PROCESSED < NO_INPUT_PROVIDED < VALID < NO_REFERENCE_AVAILABLE < INVALID < EXECUTION_ERROR

It represents the highest decision from previous decisions concerning identifier, name, locality, postcode, and thoroughfare. Therefore, the overall qualification decision in this example is VALID.

Copy

Copied

{
	"qualificationResults": [
		{
			"identifier": {
				"value": "FR35852293547",
				"type": {
					"technicalKey": "EU_VAT_ID_FR"
				}
			},
			"qualifiedAt": "2024-09-02T13:32:06.676504619",
			"dataSourceTechnicalKey": "VIES",
			"dataSourceRequestIdentifiers": [
				{
					"dataSourceTechnicalKey": "VIES",
					"value": "WAPIAAAAZGy74Ftg"
				}
			],
			"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": "WAPIAAAAZGy74Ftg"
						}
					],
					"cdqId": "VIES:FR35852293547",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-09-02T13:32:06.617922052Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZGy74Ftg"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"35852293547\"},\"requestDate\":{\"value\":\"2024-09-01T22: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\":\"WAPIAAAAZGy74Ftg\"},\"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"
				}
			]
		}
	}
}

Qualification of a German Business Partner's Identifier Only Using AT.FON

The returned response indicates that the identifier qualification decision is VALID. Since no additional attributes were introduced, all other decision attributes, except overallQualificationDecision, are set to NO_INPUT_PROVIDED. As AT.FON is being used in this instance, no confirmation in the form of a request identifier is included. AT.FON is a paid service, and when the goal is to qualify only the identifiers of German business partners, it's advisable to use the method presented in the following example.

Copy

Copied

{
	"qualificationResults": [
		{
			"identifier": {
				"value": "DE307699628",
				"type": {
					"technicalKey": "EU_VAT_ID_DE"
				}
			},
			"qualifiedAt": "2024-09-02T13:31:57.883025712",
			"dataSourceTechnicalKey": "AT.FON",
			"dataSourceRequestIdentifiers": [],
			"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 (Germany), Data source:AT.FON)",
						"url": "https://meta.cdq.com/Identifier_Qualification_(European_value_added_tax_identifier_(Germany),_Data_source:AT.FON)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Identifier deviates from the reference identifier registered with the European value added tax identifier (Germany)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "IDENTIFIER"
						},
						{
							"name": "targetInputValue",
							"value": "DE307699628"
						},
						{
							"name": "targetReferenceValue",
							"value": "DE307699628"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "AT.FON"
						}
					],
					"cdqId": "AT.FON:DE307699628",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-09-02T13:31:57.831654278Z",
				"additionalInformation": [
					{
						"key": "rawJson",
						"value": "[{\"rc\":0,\"name\":\"CDQ GmbH   \",\"adrz1\":\"Albrechtstr. 8\",\"adrz3\":\"88045\",\"adrz4\":\"Friedrichshafen\",\"uid\":\"DE307699628\",\"countryCode\":\"DE\",\"address\":{\"country\":{\"value\":\"Germany\",\"shortName\":\"DE\"},\"localities\":[{\"value\":\"Friedrichshafen\",\"shortName\":\"Friedrichshafen\",\"type\":{\"name\":\"City\",\"url\":\"https://meta.cdq.com/Address/locality/type/city\",\"technicalKey\":\"CITY\"}}],\"thoroughfares\":[{\"value\":\"Albrechtstraße\",\"number\":\"8\",\"shortName\":\"Albrechtstr.\",\"type\":{\"name\":\"Street\",\"url\":\"https://meta.cdq.com/Address/thoroughfare/type/street\",\"technicalKey\":\"STREET\"}}],\"postCodes\":[{\"value\":\"88045\"}],\"version\":{\"characterSet\":{\"name\":\"International\",\"technicalKey\":\"INTERNATIONAL\"},\"language\":{\"name\":\"en\",\"technicalKey\":\"en\"}}}}]"
					}
				]
			}
		],
		"businessRulesExecutionSummary": {
			"numberOfRules": 1,
			"numberOfExecutions": 1,
			"numberOfFails": 0,
			"failures": [],
			"dataSourcesOn": [
				{
					"prefix": "VIES"
				},
				{
					"prefix": "AT.FON"
				}
			],
			"ruleCategoriesOn": [
				{
					"url": "https://meta.cdq.com/EU_TAX_Qualification"
				}
			]
		}
	}
}

Qualification of a German Business Partner's Identifier Only Using VIES

By adding the parameter "dataSources": ["VIES"] to a request, the qualification service is directed to use VIES as the reference data source. As a result, the decision for identifier qualification remains consistent with the previous example: VALID. However, other decisions result in NOT_PROCESSED, regardless of the absence of input in this case. This approach is intentional to indicate that even if other attributes are provided, qualification isn't possible due to a lack of proper qualification rules. Therefore, the NOT_PROCESSED decision is consistently returned in this scenario. Additionally, it's important to note that even if business partner attributes were included and appropriate rules existed, qualification would still be unattainable, as VIES is unable to process German business partner attributes, except EU VAT identifiers.

Copy

Copied

{
	"qualificationResults": [
		{
			"identifier": {
				"value": "DE307699628",
				"type": {
					"technicalKey": "EU_VAT_ID_DE"
				}
			},
			"qualifiedAt": "2024-09-03T11:12:03.204540242",
			"dataSourceTechnicalKey": "VIES",
			"dataSourceRequestIdentifiers": [
				{
					"dataSourceTechnicalKey": "VIES",
					"value": "WAPIAAAAZG3laL3W"
				}
			],
			"qualificationDecisionSummary": {
				"identifierQualificationDecision": "VALID",
				"nameQualificationDecision": "NOT_PROCESSED",
				"addressQualificationDecision": "NOT_PROCESSED",
				"addressQualificationDecisionDetails": {
					"localityQualificationDecision": "NOT_PROCESSED",
					"postCodeQualificationDecision": "NOT_PROCESSED",
					"thoroughfareQualificationDecision": "NOT_PROCESSED"
				},
				"overallQualificationDecision": "VALID"
			},
			"qualificationDecisionDetails": [
				{
					"businessRule": {
						"name": "Identifier Qualification (European value added tax identifier (Germany), Data source:VIES)",
						"url": "https://meta.cdq.com/Identifier_Qualification_(European_value_added_tax_identifier_(Germany),_Data_source:VIES)",
						"ruleStatus": "RELEASED",
						"violationMessage": "Identifier deviates from the reference identifier registered with the European value added tax identifier (Germany)"
					},
					"executionContextProperties": [
						{
							"name": "qualificationTarget",
							"value": "IDENTIFIER"
						},
						{
							"name": "targetInputValue",
							"value": "DE307699628"
						},
						{
							"name": "targetReferenceValue",
							"value": "DE307699628"
						},
						{
							"name": "dataSourceTechnicalKey",
							"value": "VIES"
						},
						{
							"name": "dataSourceRequestIdentifier",
							"value": "WAPIAAAAZG3laL3W"
						}
					],
					"cdqId": "VIES:DE307699628",
					"decision": "VALID"
				}
			]
		}
	],
	"lookupResults": [],
	"debugInfo": {
		"externalServiceResponses": [
			{
				"status": 200,
				"timestamp": "2024-09-03T11:12:03.145729079Z",
				"additionalInformation": [
					{
						"key": "requestorId",
						"value": "DE307699628"
					},
					{
						"key": "requestId",
						"value": "WAPIAAAAZG3laL3W"
					},
					{
						"key": "rawJson",
						"value": "[{\"vatValue\":{\"value\":\"307699628\"},\"requestDate\":{\"value\":\"2024-09-02T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"DE\"},\"valid\":{\"value\":true},\"traderAddress\":{},\"traderName\":{},\"traderCompanyType\":{},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{},\"traderCompanyTypeMatch\":{},\"traderStreetMatch\":{},\"traderPostcodeMatch\":{},\"traderCityMatch\":{},\"requestIdentifier\":{\"value\":\"WAPIAAAAZG3laL3W\"},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\",\"refreshReason\":\"FORCED_BY_CUSTOMER\"}]"
					}
				]
			}
		],
		"businessRulesExecutionSummary": {
			"numberOfRules": 1,
			"numberOfExecutions": 1,
			"numberOfFails": 0,
			"failures": [],
			"dataSourcesOn": [
				{
					"prefix": "VIES"
				}
			],
			"ruleCategoriesOn": [
				{
					"url": "https://meta.cdq.com/Qualification"
				},
				{
					"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.

Conclusion

This tutorial provided a detailed explanation of how to qualify a Business Partner using identifiers. It's important to understand qualification results and analyze them to ensure that the Business Partner is correctly qualified. The response structure and VIES limitations were also discussed to provide a comprehensive understanding of the qualification process.

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