Business Partners

Everything about Business Partners

Qualify Business PartnerBETA

BETA
Endpoint used for Business Partner qualification. It is in BETA version and may change without notice.

SecurityapiKey

Request

Request Body schema: application/json
required

cmd

object (BusinessPartner)

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

dataSources

Array of strings (DataSourcesEnum)

List of data sources should be used.

Items Enum:	Description
AR.NRC	Value indicating AR.NRC data source.
AT.CR	Value indicating AT.CR data source.
AT.FON	Value indicating AT.FON data source.
AU.BR	Value indicating AU.BR data source.
BR.RF	Value indicating BR.RF data source.
BZST	Value indicating BZST data source.
CA.CR	Value indicating CA.CR data source.
CH.UIDR	Value indicating CH.UIDR data source.
CZ.REE	Value indicating CZ.REE data source.
DK.CR	Value indicating DK.CR data source.
EU.EORI	Value indicating EU.EORI data source.
FR.RC	Value indicating FR.RC data source.
NO.RBE	Value indicating NO.RBE data source.
PL.NOBR	Value indicating PL.NOBR data source.
SG.BR	Value indicating SG.BR data source.
UK.EORI	Value indicating UK.EORI data source.
UK.VAT	Value indicating UK.VAT data source.
VIES	Value indicating VIES data source.

Example: ["AR.NRC"]

featuresOff

Array of strings (BusinessPartnerQualificationRequestFeaturesEnum)

Request features that should be turned off.

Items Enum:	Description
SHOW_LOOKUP_RESULTS	Includes lookup results in the response.
SHOW_BUSINESS_PARTNER	Includes Business Partner in the response.
FORCE_EXTERNAL_CALL	Forces calls on external services ignoring cache.
SHOW_DEBUG_INFO	Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).

Example: ["FORCE_EXTERNAL_CALL"]

featuresOn

Array of strings (BusinessPartnerQualificationRequestFeaturesEnum)

Request features that should be turned on.

Items Enum:	Description
SHOW_LOOKUP_RESULTS	Includes lookup results in the response.
SHOW_BUSINESS_PARTNER	Includes Business Partner in the response.
FORCE_EXTERNAL_CALL	Forces calls on external services ignoring cache.
SHOW_DEBUG_INFO	Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).

Example: ["FORCE_EXTERNAL_CALL"]

profile

string (BusinessPartnerQualificationRequestProfileEnum)

Default: "EU_TAX_QUALIFICATION"

Qualification profiles enum.

Enum:	Description
EU_TAX_QUALIFICATION	Default option. EU_TAX_QUALIFICATION profile for the Qualification process.
WORLDWIDE_TAX_QUALIFICATION	WORLDWIDE_TAX_QUALIFICATION profile for the Qualification process.

Example: "EU_TAX_QUALIFICATION"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

post/v3/businesspartners/qualify

Request samples

Payload
curl
Python
Java
Node.js

application/json

{"profile": "EU_TAX_QUALIFICATION",
"businessPartner": {"names": [{"value": "ATOS SPAIN SA"
}
],
"identifiers": [{"type": {"technicalKey": "EU_VAT_ID_ES"
},
"value": "A28240752"
}
],
"addresses": [{"country": {"shortName": "ES"
}
}
]
}
}

Response samples

application/json

{"qualificationResults": [{"identifier": {"value": "A28240752",
"type": {"technicalKey": "EU_VAT_ID_ES"
}
},
"qualifiedAt": "2023-10-03T16:37:19.252354829",
"qualificationDecisionSummary": {"identifierQualificationDecision": "VALID",
"nameQualificationDecision": "VALID",
"addressQualificationDecision": "NO_INPUT_PROVIDED",
"addressQualificationDecisionDetails": {"localityQualificationDecision": "NO_INPUT_PROVIDED",
"postCodeQualificationDecision": "NO_INPUT_PROVIDED",
"thoroughfareQualificationDecision": "NO_INPUT_PROVIDED"
},
"overallQualificationDecision": "VALID"
},
"qualificationDecisionDetails": [{"businessRule": {"name": "Name Qualification (European value added tax identifier (Spain), Data source:VIES)",
"url": "https://meta.cdq.com/Name_Qualification_(European_value_added_tax_identifier_(Spain),_Data_source:VIES)",
"ruleStatus": "HYPERCARE",
"violationMessage": "Name deviates from the reference name registered with the European value added tax identifier (Spain)"
},
"executionContextProperties": [{"type": "qualificationTarget",
"value": "NAME_LOCAL"
},
{"type": "targetInputValue",
"value": "ATOS SPAIN SA"
},
{"type": "targetReferenceValue",
"value": "ATOS SPAIN SA"
}
],
"dataSourceTechnicalKey": "VIES",
"cdqId": "VIES:ESA28240752",
"decision": "VALID",
"error": { }
}
]
}
],
"lookupResults": [{"businessPartner": {"addresses": [{"version": {"characterSet": {"technicalKey": "LATIN"
},
"language": {"name": "en",
"technicalKey": "en"
}
},
"country": {"shortName": "ES",
"value": "Spain"
}
}
],
"names": [{"type": {"url": "https://meta.cdq.com/Business_partner/name/type/vat_registered_name",
"name": "VAT Registered Name",
"technicalKey": "VAT_REGISTERED"
},
"value": "ATOS SPAIN SA",
"language": { }
}
],
"identifiers": [{"value": "ESA28240752",
"type": {"url": "https://meta.cdq.com/European_value_added_tax_identifier_(Spain)",
"name": "Value added tax identification number",
"technicalKey": "EU_VAT_ID_ES"
},
"issuingBody": { }
}
],
"legalForm": {"name": "Sociedad Anónima",
"mainAbbreviation": "S.A.",
"url": "https://meta.cdq.com/Business_partner/legal_form/technical_key/ES_1035",
"technicalKey": "ES_1035"
},
"status": { },
"profile": { }
},
"address": { },
"dataSource": "VIES",
"cdqId": "VIES:ESA28240752"
}
],
"debugInfo": {"externalServiceResponses": [{"status": 200,
"timestamp": "2023-10-03T14:37:19.125086Z",
"additionalInformation": [{"key": "requestorId",
"value": "DE307699628"
},
{"key": "requestId",
"value": "WAPIAAAAYr1-NB3H"
},
{"key": "rawJson",
"value": "[{\"vatValue\":{\"value\":\"A28240752\"},\"requestDate\":{\"value\":\"2023-10-02T22:00:00.000+00:00\"},\"countryCode\":{\"value\":\"ES\"},\"valid\":{\"value\":true},\"traderAddress\":{},\"traderName\":{\"value\":\"ATOS SPAIN SA\"},\"traderCompanyType\":{},\"traderStreet\":{},\"traderPostcode\":{},\"traderCity\":{},\"traderNameMatch\":{\"value\":\"1\"},\"traderCompanyTypeMatch\":{\"value\":\"3\"},\"traderStreetMatch\":{\"value\":\"3\"},\"traderPostcodeMatch\":{\"value\":\"3\"},\"traderCityMatch\":{\"value\":\"3\"},\"requestIdentifier\":{\"value\":\"WAPIAAAAYr1-NB3H\"},\"requesterVatNumber\":\"307699628\",\"requesterCountryCode\":\"DE\"}]"
}
]
}
],
"businessRulesExecutionSummary": {"numberOfRules": 0,
"numberOfExecutions": 0,
"numberOfFails": 0
}
}
}

Validate Business PartnerWSDL

Validate business partners (i.e. identifiers, legal forms) and addresses (i.e. post codes) and receive a list of data defects in case of found data quality issues.

Examples

Check out our examples in the Try it console to better understand this endpoint.

Example	Description
Identifier exists and is valid	No `dataDefects` related to the identifier and `identifierReliability.level` equals `4`. Note that there might be data defects if you provide more details than the identifier (i.e. address data).
Identifier does not exist in external data source	Entry in `dataDefects` related to the identifier and `identifierReliability.level` < 4
Unknown status for an identifier existence (only response example)	`identifierReliability.level` < `4` and the respective `message` equals to `external service error`. You may try again as this is typical a temporary issue.

SecurityapiKey

Request

Request Body schema: application/json

activatedRules

Array of strings (BusinessRuleUrl)

Urls of cdl rules that are active during validation process.

Example: ["https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"]

required

object (BusinessPartnerParam)

Refers to an organizational entity engaged in various facets of another organization's business interactions. This collaborative connection often manifests as a customer, supplier, vendor, or service provider. In the CDQ (Corporate Data Quality) framework, the Business Partner assumes a pivotal role as a core managed entity. Each Business Partner is distinctly and globally identifiable through a unique CDQ ID. All pertinent information, including addresses, identifiers, and hierarchical data, is intricately associated with and linked to the specific Business Partner, ensuring comprehensive management and traceability within the system.

bzstPrint

string

Request printed confirmation by German BZSt authority.

Example: "true"

configurationId

string (ConfigurationId)

Configuration ID used to set up data validation request. If provided, those parameters will be overridden:

profile
featuresOn
featuresOff

Example: "6513d25b63cf07787018790a"

Array of objects (Criticality)

Array of objects (DataSource)

Rules with data sources passed here are not used in validation process.

Array of objects (DataSource)

If data sources are disabled by feature toggle you can enable some of them passing their prefixes here.

featuresOff

Array of strings (ValidationFeature)

List of deactivated features.

Items Enum:	Description
ADDRESS_CHECKS	CDQ data quality profiling services enable the validation of addresses with respect to different data quality criteria.
BANKING_DATA_CHECKS	CDQ data quality profiling services enable the validation of bank master data with respect to different data quality criteria.
BUSINESS_PARTNER_CHECKS	Validate concepts that basically establish a business partner (e.g. name and legal form).
COUNTRY_CHECKS	Validate country information.
ENRICH_CATEGORIES	Enrich a CDL community standardized business partner category for a given entity.
ENRICH_DATA_MIRROR_CHANGES	Enriches the data with changes from the data mirror.
ENRICH_LEGAL_FORM	Identify and enriches the legal form of a company.
EU_VAT_QUALIFICATION_AT	Enforces to use AT.FON data source to qualify EU VATs.
EU_VAT_QUALIFICATION_DE	Enforces to use BZST data source for non-German business partners.
EU_VAT_QUALIFICATION_STANDARD	For a given EU VAT, it is checked whether the name and address are really associated with this identifier (same information maintained in the VAT register as provided by the user).
EXTERNAL_SOURCES_OFF	Turns off external data sources.
FORCE_EXTERNAL_CALL	Force external call.
IDENTIFIER_CHECKS	Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.
IDENTIFIER_QUALIFICATION	Turns on identifier qualification (standard) which enables to qualify EU VAT identifiers.
LAB_BETA	Deprecated feature.
QUALIFICATION_SILENT_MODE	If enabled all exceptions occurring within execution of business rules are ignored. If not enabled then execution error will result in creating data defect. By default, part of profile QUALIFICATION.
SHOW_BUSINESSPARTNER	Shows business partner that was used in the request.
SHOW_DATA_DEFECTS	Shows found data defects - usually it is turned on.
SHOW_DEBUG_INFO	Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).
SHOW_DECISIONS	Deprecated feature.
SHOW_LOOKUP_RESULTS	Displays results from the lookup endpoint (usually enriched data in comparison to the original business partner requested).
SHOW_QUALIFICATION_DECISIONS	Shows qualification decisions - used only in qualification endpoint in API v3. In APIv1 and APIv2 it is used in validation endpoint.
USE_SPARQL_VALIDATOR	Deprecated feature.

Example: ["SHOW_LOOKUP_RESULTS"]

featuresOn

Array of strings (ValidationFeature)

List of activated features.

Items Enum:	Description
ADDRESS_CHECKS	CDQ data quality profiling services enable the validation of addresses with respect to different data quality criteria.
BANKING_DATA_CHECKS	CDQ data quality profiling services enable the validation of bank master data with respect to different data quality criteria.
BUSINESS_PARTNER_CHECKS	Validate concepts that basically establish a business partner (e.g. name and legal form).
COUNTRY_CHECKS	Validate country information.
ENRICH_CATEGORIES	Enrich a CDL community standardized business partner category for a given entity.
ENRICH_DATA_MIRROR_CHANGES	Enriches the data with changes from the data mirror.
ENRICH_LEGAL_FORM	Identify and enriches the legal form of a company.
EU_VAT_QUALIFICATION_AT	Enforces to use AT.FON data source to qualify EU VATs.
EU_VAT_QUALIFICATION_DE	Enforces to use BZST data source for non-German business partners.
EU_VAT_QUALIFICATION_STANDARD	For a given EU VAT, it is checked whether the name and address are really associated with this identifier (same information maintained in the VAT register as provided by the user).
EXTERNAL_SOURCES_OFF	Turns off external data sources.
FORCE_EXTERNAL_CALL	Force external call.
IDENTIFIER_CHECKS	Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.
IDENTIFIER_QUALIFICATION	Turns on identifier qualification (standard) which enables to qualify EU VAT identifiers.
LAB_BETA	Deprecated feature.
QUALIFICATION_SILENT_MODE	If enabled all exceptions occurring within execution of business rules are ignored. If not enabled then execution error will result in creating data defect. By default, part of profile QUALIFICATION.
SHOW_BUSINESSPARTNER	Shows business partner that was used in the request.
SHOW_DATA_DEFECTS	Shows found data defects - usually it is turned on.
SHOW_DEBUG_INFO	Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).
SHOW_DECISIONS	Deprecated feature.
SHOW_LOOKUP_RESULTS	Displays results from the lookup endpoint (usually enriched data in comparison to the original business partner requested).
SHOW_QUALIFICATION_DECISIONS	Shows qualification decisions - used only in qualification endpoint in API v3. In APIv1 and APIv2 it is used in validation endpoint.
USE_SPARQL_VALIDATOR	Deprecated feature.

Example: ["SHOW_LOOKUP_RESULTS"]

ignoredRules

Array of strings (BusinessRuleUrl)

Urls of cdl rules ignored during validation process.

Example: ["https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"]

profile

string (ValidationProfile)

Profile which is used during validation. Default value is STANDARD.

Enum:	Description
QUICK	This profile checks data quality of records in a quick way, i.e. data quality rules that have a negative impact on performance.
STANDARD	This profile checks data quality using CDQ's standard configuration.
QUALIFICATION	Deprecated.
AUTOMATION	Deprecated.
EU_VAT_QUALIFICATION	This profile qualifies EU VATs using CDQ's default configuration of data quality rules for qualified checks of EU VATs
DATA_SHARING_QUALITY_GATE	Quality checks ensure that only valid data enters the CDQ Community Data Pool
IDENTIFIER_QUALITY	This profile checks identifiers with a standard configuration of data quality rules. It does not comprise qualified checks of identifiers regarding e.g. name or address.
ADDRESS_QUALITY	This profile checks addresses with a standard configuration of data quality rules.
WORLDWIDE_IDENTIFIER_QUALIFICATION	This profile qualifies any supported business identifier (e.g. tax numbers) worldwide using CDQ's default configuration of data quality rules for qualified checks of a particular identifier
FEATURES_OFF	This profile turns off any qualification rules and is designed for custom rules selection.

Example: "QUICK"

Array of objects (RuleCategoryOn)

Categories use for selecting active business rules.

ruleStatuses

Array of strings (RuleStatus)

Enable rules with provided statuses.

Items Enum:	Description
RELEASED	Rule was moved from status PLANNED automatically during daily testing or by manual maintenance.
DRAFT	Rule was created as a draft and it will be not executed.
HYPERCARE	Rule was moved from status DEACTIVATED automatically during daily testing.

Example: ["RELEASED"]

object (ValidationSource)

Source of the validation.

vatAtRequestor

string

Deprecated

DEPRECATED, use organizational settings to configure.

The requestor’s VAT identifier, required for execution of requests against external data sources.

Example: "AT123456789"

vatDeRequestor

string

Deprecated

DEPRECATED, use organizational settings to configure.

The requestor’s VAT identifier, required for execution of requests against external data sources.

Example: "DE123456789"

Responses

200

post/v2/businesspartners/validate

Request samples

Payload
curl
Python
Java
Node.js

application/json

{"businessPartner": {"names": [{"value": "CDQ AG"
}
],
"identifiers": [{"value": "218.608.886",
"type": {"technicalKey": "CH_UID"
}
}
],
"legalForm": {"name": "Aktiengesellschaft"
},
"addresses": [{"country": {"shortName": "CH"
},
"thoroughfares": [{"value": "Lukasstrassse 4"
}
],
"localities": [{"value": "St.Gallen"
}
],
"postCodes": [{"value": "9008"
}
]
}
]
}
}

Response samples

{"summary": {"validationLevel": "OK",
"action": "AUTO_APPROVE",
"statistics": {"numberOfInfoDataDefects": 0,
"numberOfErrorDataDefects": 0,
"numberOfWarningDataDefects": 0
}
},
"debugInfo": {"businessRulesExecutionSummary": {"numberOfRules": 398,
"numberOfExecutions": 398,
"numberOfFails": 0,
"ruleCategoriesOn": [{"url": "https://meta.cdq.com/Identifier_checkdigit"
},
{"url": "https://meta.cdq.com/Country_invalid"
},
{"url": "https://meta.cdq.com/Identifier_consistency"
},
{"url": "https://meta.cdq.com/Identifier_missing"
},
{"url": "https://meta.cdq.com/Identifier_format"
},
{"url": "https://meta.cdq.com/Identifier_deprecation"
},
{"url": "https://meta.cdq.com/Identifier_existence"
},
{"url": "https://meta.cdq.com/Identifier_schema"
}
],
"violationLevels": ["INFO",
"WARNING",
"ERROR"
]
}
},
"identifierResults": [{"property": {"value": "DE307699628",
"type": "EU_VAT_ID_DE"
},
"reliabilityLevel": {"name": "Identifier existence",
"url": "https://meta.cdq.com/Identifier_existence",
"value": 4,
"checks": [{"name": "Identifier checkdigit",
"url": "https://meta.cdq.com/Identifier_checkdigit",
"value": 3,
"status": "OK"
},
{"name": "Identifier existence",
"url": "https://meta.cdq.com/Identifier_existence",
"value": 4,
"status": "OK"
},
{"name": "Identifier format",
"url": "https://meta.cdq.com/Identifier_format",
"value": 2,
"status": "OK"
}
]
}
}
],
"businessPartner": {"legalForm": { },
"identifiers": [{"value": "DE307699628",
"type": {"technicalKey": "EU_VAT_ID_DE"
},
"issuingBody": { }
}
],
"addresses": [{"version": {"characterSet": { },
"language": { }
},
"country": {"shortName": "DE",
"value": "Germany"
}
}
],
"profile": { }
}
}

Business Partners

Qualify Business PartnerBETA

Request Body schema: application/jsonrequired

Validate Business PartnerWSDL

Examples

Request Body schema: application/json

Request Body schema: application/json
required