Skip to content

Data Validation API (3)

This API provides services used for business partner qualification

Data Validation API
Overview
URL

https://www.cdq.ch/team

Paweł Siwoń

pawel.siwon@cdq.com

Languages
Servers
Mock server

https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/

Production SOAP

https://api.corporate-data-league.ch/data-validation/soap/v3/

Production

https://api.corporate-data-league.ch/data-validation/

Qualification

Provides funcionalities for qualification of Business Partners. Includes endpoints that allow users to submit Business Partner data for qualification, retrieve qualification results, and handle various qualification scenarios.

Operations

Validation

Provides funcionalities for validation of Business Partner data.

Operations

Batch Validation

Provides funcionalities for validation of multiple records or entities in a single request. Includes endpoints that allow users to start validation jobs, poll the status of these jobs, and retrieve validation results.

Operations

Start Validation Job

Request

Starts a new Validation Job on a provided storage ID.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
profilestring(ValidationProfile)

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

Enum ValueDescription
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"
featuresOnArray of strings

List of features to be activated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
featuresOffArray of strings

List to be deactivated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleStatusesArray of strings(RuleStatus)

Enable rules with provided statuses

Items Enum ValueDescription
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"]
jobDependenciesArray of objects(JobDependency)
labelsArray of objects(Label)
tagsArray of strings(JobTags)<= 12 items

List of tags.

Example: ["35f23c03-1c22-45fe-9484-3ffe769325de"]
bzstPrintstring

Request printed confirmation by German BZSt authority

Example: true
validationSourceobject(ValidationSource)

Source of the validation.

reportsRequestobject(ValidationReportsRequestParams)

Parameters for Validation Reports.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

vatAtRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "AT123456789"
vatDeRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "DE123456789"
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/validationjobs \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "profile": "QUICK",
    "featuresOn": [
      "SHOW_LOOKUP_RESULTS"
    ],
    "featuresOff": [
      "SHOW_LOOKUP_RESULTS"
    ],
    "ruleStatuses": [
      "RELEASED"
    ],
    "jobDependencies": [
      {
        "id": "c2a0b3a0-8b0b-4b7a-8b0b-4b7a8b0b4b7a",
        "strategy": "SCHEDULE_NEXT_WHEN_FINISHED"
      }
    ],
    "labels": [
      {
        "key": "domain",
        "value": "data-validation"
      }
    ],
    "tags": [
      "35f23c03-1c22-45fe-9484-3ffe769325de"
    ],
    "vatAtRequestor": "AT123456789",
    "vatDeRequestor": "DE123456789",
    "bzstPrint": true,
    "validationSource": {
      "type": {
        "technicalKey": "VALIDATION_GRAPH",
        "description": "Default CDL Model"
      },
      "value": "CDL"
    },
    "reportsRequest": {
      "reportsConfiguration": {
        "address": {
          "build": "true"
        },
        "businesspartner": {
          "build": "true"
        },
        "identifier": {
          "build": "true"
        },
        "overall": {
          "build": "true"
        },
        "qualification": {
          "build": "true"
        },
        "qualityImprovement": {
          "build": "true",
          "dataValidationJobIds": [
            "6be92567-4327-4463-813f-a8c990410d79",
            "f9df6cd4-4414-4719-9fb5-4eb6e5bc04cb"
          ]
        },
        "countryShortNames": "['\''PL'\'', '\''DE'\'', '\''CZ'\'', '\''SK'\'']"
      },
      "labels": [
        {
          "key": "domain",
          "value": "data-validation"
        }
      ],
      "tags": [
        "35f23c03-1c22-45fe-9484-3ffe769325de"
      ]
    },
    "dataSourcesOn": [
      {
        "prefix": "VIES"
      }
    ],
    "dataSourcesOff": [
      {
        "prefix": "VIES"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
idstring(DataValidationJobId)

Data Validation Job ID.

Example: "ef450653-a3bc-4476-83d3-d67397d475a0"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring

Current status of the job.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job couldn't start.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

FAILED

Job has failed.

Example: "FINISHED"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

Describe when this job was first established.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(JobUser)

ID of (human) user or API key.

Example: "742429-234242-4343-232323"
resultobject(ValidationJobResult)

Created when validation process takes into consideration rules of category and the feature SHOW_DECISIONS is enabled. Enabling validation can be done by the profile related to the validation. ValidationJobResult contains information about validation decisions, the data that have been validated and overall validation decisions.

progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
Response
application/json
{
  "id": "ef450653-a3bc-4476-83d3-d67397d475a0",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "FINISHED",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "742429-234242-4343-232323",
  "result": {
    "statistics": { … },
    "images": { … }
  },
  "progress": "77"
}

Poll Validation Job

Request

After you have started a validation job, you will receive a job id in the response. { "id" : "<ID>" } Use this ID to poll for the status of the job using this endpoint.

Security
basicAuth
Path
idstring(DataValidationJobId)required

ID of the validation report.

Example: ef450653-a3bc-4476-83d3-d67397d475a0
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/validationjobs/ef450653-a3bc-4476-83d3-d67397d475a0 \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
idstring(DataValidationJobId)

Data Validation Job ID.

Example: "ef450653-a3bc-4476-83d3-d67397d475a0"
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
statusstring

Current status of the job.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job couldn't start.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

FAILED

Job has failed.

Example: "FINISHED"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

Describe when this job was first established.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(JobUser)

ID of (human) user or API key.

Example: "742429-234242-4343-232323"
resultobject(ValidationJobResult)

Created when validation process takes into consideration rules of category and the feature SHOW_DECISIONS is enabled. Enabling validation can be done by the profile related to the validation. ValidationJobResult contains information about validation decisions, the data that have been validated and overall validation decisions.

progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
Response
application/json
{
  "id": "ef450653-a3bc-4476-83d3-d67397d475a0",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "status": "FINISHED",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "742429-234242-4343-232323",
  "result": {
    "statistics": { … },
    "images": { … }
  },
  "progress": "77"
}

Poll Record Validation Job

Request

Polls the status of a record validation job. The job is finished when the status is either FINISHED or FAILED. If the job is finished, the result can be fetched using the /v2/recordvalidationjobs/{id}/results endpoint.

Security
basicAuth
Path
idstring(DataValidationJobId)required

ID of the validation report.

Example: ef450653-a3bc-4476-83d3-d67397d475a0
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/recordvalidationjobs/ef450653-a3bc-4476-83d3-d67397d475a0 \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
customKnowledgeGraphstringrequired

Identifier for the custom knowledge graph that should be used for validation.

Example: "kg_1_m_1"
dataMapperDefinitionIdstring(DataMapperDefinitionId)

Mapping ID that should be used for the mapping. Overrules a mapping of the knowledge graph (if exists). To run validation against CDL Rules, data mapping definition by given ID must exist and user executing validation needs to have permission to access it.

Example: "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20"
profilestring

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

Enum ValueDescription
QUICK

This profile checks data quality of records in a quick way, i.e. data quality rules that have a negative impact on performance (e.g. rules that use external webservices) are not executed. It does not provide a full check comprising all data quality rules, but allows for a rapid, initial assessment of data quality.

STANDARD

This profile checks data quality using CDQ's standard configuration

Example: "QUICK"
ruleStatusesArray of strings(RuleStatus)

Filter for rule status.

Items Enum ValueDescription
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"]
featuresOnArray of strings

Activate features.

Items Enum ValueDescription
SHOW_LOOKUP_RESULTS

Displays results from the lookup endpoint (usually enriched data in comparison to the original business partner requested).

SHOW_DEBUG_INFO

Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).

LAB_BETA

Deprecated feature.

ENRICH_LEGAL_FORM

Identify and enriches the legal form of a company.

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

USE_SPARQL_VALIDATOR

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.

EXTERNAL_SOURCES_OFF

Turns off external data sources.

SHOW_BUSINESSPARTNER

Shows business partner that was used in the request.

MED_REG_VALIDATION

If enabled it will execute validation only for MED_REG records. Applies only to Record Validation Job.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleCategoriesOnArray of objects(RuleCategory)

Categories use for selecting active business rules.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
jobDependenciesArray of objects(JobDependency)

List of job dependencies.

labelsArray of objects(Label)

List of labels.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
statusstring

Current status of the job.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job couldn't start.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

FAILED

Job has failed.

Example: "FINISHED"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

Describe when this job was first established.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(JobUser)

ID of (human) user or API key.

Example: "742429-234242-4343-232323"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
resultobject(RecordValidationResult)

Contains information about created record during Validation Process.

Response
application/json
{
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "customKnowledgeGraph": "kg_1_m_1",
  "dataMapperDefinitionId": "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20",
  "profile": "QUICK",
  "ruleStatuses": [
    "RELEASED"
  ],
  "featuresOn": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "ruleCategoriesOn": [
    { … }
  ],
  "ignoredRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "activatedRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "jobDependencies": [
    { … }
  ],
  "labels": [
    { … }
  ],
  "dataSourcesOn": [
    { … }
  ],
  "dataSourcesOff": [
    { … }
  ],
  "updatedFrom": "2020-07-06T12:14:03.204Z",
  "dataSourceIds": [
    "648824a691d8d2503d65103e"
  ],
  "countryShortNames": [
    "CH"
  ],
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "status": "FINISHED",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "742429-234242-4343-232323",
  "progress": "77",
  "result": {
    "dataDefects": [ … ],
    "decisions": [ … ],
    "qualificationResult": { … },
    "summary": { … },
    "debugInfo": { … },
    "diff": "{\"Identified_changes\":[{\"op\":\"add\",\"path\":\"/partner/header/objectTask\",\"value\":\"C\"}]}",
    "businessPartner": { … }
  }
}

Start Record Validation Job

Request

Starts a new validation job on a provided storage ID.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
customKnowledgeGraphstringrequired

Identifier for the custom knowledge graph that should be used for validation.

Example: "kg_1_m_1"
dataMapperDefinitionIdstring(DataMapperDefinitionId)

Mapping ID that should be used for the mapping. Overrules a mapping of the knowledge graph (if exists). To run validation against CDL Rules, data mapping definition by given ID must exist and user executing validation needs to have permission to access it.

Example: "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20"
profilestring

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

Enum ValueDescription
QUICK

This profile checks data quality of records in a quick way, i.e. data quality rules that have a negative impact on performance (e.g. rules that use external webservices) are not executed. It does not provide a full check comprising all data quality rules, but allows for a rapid, initial assessment of data quality.

STANDARD

This profile checks data quality using CDQ's standard configuration

Example: "QUICK"
ruleStatusesArray of strings(RuleStatus)

Filter for rule status.

Items Enum ValueDescription
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"]
featuresOnArray of strings

Activate features.

Items Enum ValueDescription
SHOW_LOOKUP_RESULTS

Displays results from the lookup endpoint (usually enriched data in comparison to the original business partner requested).

SHOW_DEBUG_INFO

Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).

LAB_BETA

Deprecated feature.

ENRICH_LEGAL_FORM

Identify and enriches the legal form of a company.

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

USE_SPARQL_VALIDATOR

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.

EXTERNAL_SOURCES_OFF

Turns off external data sources.

SHOW_BUSINESSPARTNER

Shows business partner that was used in the request.

MED_REG_VALIDATION

If enabled it will execute validation only for MED_REG records. Applies only to Record Validation Job.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleCategoriesOnArray of objects(RuleCategory)

Categories use for selecting active business rules.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
jobDependenciesArray of objects(JobDependency)

List of job dependencies.

labelsArray of objects(Label)

List of labels.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/recordvalidationjobs \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "storageId": "72d6900fce6b326088f5d9d91049e3e6",
    "customKnowledgeGraph": "kg_1_m_1",
    "dataMapperDefinitionId": "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20",
    "profile": "QUICK",
    "ruleStatuses": [
      "RELEASED"
    ],
    "featuresOn": [
      "SHOW_LOOKUP_RESULTS"
    ],
    "ruleCategoriesOn": [
      {
        "url": "https://meta.cdq.com/Identifier_checkdigit",
        "name": "Identifier checkdigit"
      }
    ],
    "ignoredRules": [
      "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
    ],
    "activatedRules": [
      "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
    ],
    "jobDependencies": [
      {
        "id": "c2a0b3a0-8b0b-4b7a-8b0b-4b7a8b0b4b7a",
        "strategy": "SCHEDULE_NEXT_WHEN_FINISHED"
      }
    ],
    "labels": [
      {
        "key": "domain",
        "value": "data-validation"
      }
    ],
    "dataSourcesOn": [
      {
        "prefix": "VIES"
      }
    ],
    "dataSourcesOff": [
      {
        "prefix": "VIES"
      }
    ],
    "updatedFrom": "2020-07-06T12:14:03.204Z",
    "dataSourceIds": [
      "648824a691d8d2503d65103e"
    ],
    "countryShortNames": [
      "CH"
    ]
  }'

Responses

OK

Bodyapplication/json
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
customKnowledgeGraphstringrequired

Identifier for the custom knowledge graph that should be used for validation.

Example: "kg_1_m_1"
dataMapperDefinitionIdstring(DataMapperDefinitionId)

Mapping ID that should be used for the mapping. Overrules a mapping of the knowledge graph (if exists). To run validation against CDL Rules, data mapping definition by given ID must exist and user executing validation needs to have permission to access it.

Example: "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20"
profilestring

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

Enum ValueDescription
QUICK

This profile checks data quality of records in a quick way, i.e. data quality rules that have a negative impact on performance (e.g. rules that use external webservices) are not executed. It does not provide a full check comprising all data quality rules, but allows for a rapid, initial assessment of data quality.

STANDARD

This profile checks data quality using CDQ's standard configuration

Example: "QUICK"
ruleStatusesArray of strings(RuleStatus)

Filter for rule status.

Items Enum ValueDescription
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"]
featuresOnArray of strings

Activate features.

Items Enum ValueDescription
SHOW_LOOKUP_RESULTS

Displays results from the lookup endpoint (usually enriched data in comparison to the original business partner requested).

SHOW_DEBUG_INFO

Shows additional information about validation process (number of applied rules, used categories, failed executions etc.).

LAB_BETA

Deprecated feature.

ENRICH_LEGAL_FORM

Identify and enriches the legal form of a company.

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

USE_SPARQL_VALIDATOR

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.

EXTERNAL_SOURCES_OFF

Turns off external data sources.

SHOW_BUSINESSPARTNER

Shows business partner that was used in the request.

MED_REG_VALIDATION

If enabled it will execute validation only for MED_REG records. Applies only to Record Validation Job.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleCategoriesOnArray of objects(RuleCategory)

Categories use for selecting active business rules.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
jobDependenciesArray of objects(JobDependency)

List of job dependencies.

labelsArray of objects(Label)

List of labels.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
statusstring

Current status of the job.

Enum ValueDescription
UNKNOWN

Job becomes in unknown status.

CREATED

Job has been created.

PERSISTED

Job metadata has been persisted.

SCHEDULED

Job has been scheduled for execution.

WAITING

Job is waiting for being scheduled.

COULDNT_START

Job couldn't start.

RUNNING

Job is being executed.

FINISHED

Job has finished.

DIED

Job has died due to unhandled exceptions.

FAILED

Job has failed.

Example: "FINISHED"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

Describe when this job was first established.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(JobUser)

ID of (human) user or API key.

Example: "742429-234242-4343-232323"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
resultobject(RecordValidationResult)

Contains information about created record during Validation Process.

Response
application/json
{
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "customKnowledgeGraph": "kg_1_m_1",
  "dataMapperDefinitionId": "ef48bc9f-7fa1-4c4e-8c0d-d1cc3301cc20",
  "profile": "QUICK",
  "ruleStatuses": [
    "RELEASED"
  ],
  "featuresOn": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "ruleCategoriesOn": [
    { … }
  ],
  "ignoredRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "activatedRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "jobDependencies": [
    { … }
  ],
  "labels": [
    { … }
  ],
  "dataSourcesOn": [
    { … }
  ],
  "dataSourcesOff": [
    { … }
  ],
  "updatedFrom": "2020-07-06T12:14:03.204Z",
  "dataSourceIds": [
    "648824a691d8d2503d65103e"
  ],
  "countryShortNames": [
    "CH"
  ],
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "status": "FINISHED",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "742429-234242-4343-232323",
  "progress": "77",
  "result": {
    "dataDefects": [ … ],
    "decisions": [ … ],
    "qualificationResult": { … },
    "summary": { … },
    "debugInfo": { … },
    "diff": "{\"Identified_changes\":[{\"op\":\"add\",\"path\":\"/partner/header/objectTask\",\"value\":\"C\"}]}",
    "businessPartner": { … }
  }
}

List Record Validation Batch Results

Request

Retrieve the results of a record validation job.

Security
basicAuth
Path
idstringrequired

ID of the Record Validation Job.

Example: 6be92567-4327-4463-813f-a8c990410d79
Query
recordIdArray of strings

Record IDs which should be filtered.

Example: recordId=6be92567-4327-4463-813f-a8c990410d79
startAfterstring(StartAfter)

Used to retrieve the next page of results.

Example: startAfter=5712566172571652
limitinteger(Limit)

Number of results that should be fetched. Maximum 100 results can be returned in one page.

Example: limit=100
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/recordvalidationjobs/6be92567-4327-4463-813f-a8c990410d79/results \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(RecordValidationResult)

List of validation results.

nextStartAfterstring(NextStartAfter)

Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
Response
application/json
{
  "startAfter": "5712566172571652",
  "limit": "100",
  "total": "67",
  "values": [
    { … }
  ],
  "nextStartAfter": "5712566172571652"
}

Start Business Partner Validation Job

Request

Start a new validation job on a provided storage ID.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
profilestring(ValidationProfile)

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

Enum ValueDescription
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"
featuresOnArray of strings

List of features to be activated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
featuresOffArray of strings

List to be deactivated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleStatusesArray of strings(RuleStatus)

Enable rules with provided statuses

Items Enum ValueDescription
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"]
jobDependenciesArray of objects(JobDependency)
labelsArray of objects(Label)
tagsArray of strings(JobTags)<= 12 items

List of tags.

Example: ["35f23c03-1c22-45fe-9484-3ffe769325de"]
bzstPrintstring

Request printed confirmation by German BZSt authority

Example: true
validationSourceobject(ValidationSource)

Source of the validation.

reportsRequestobject(ValidationReportsRequestParams)

Parameters for Validation Reports.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

ruleCategoriesOnArray of objects(RuleCategory)

List of rule categories that are used to filter rules by its category. If any value is present then only rules of given category will be promoted to execution.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
configurationIdstring(ConfigurationId)

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

  • profile
  • featuresOn
  • featuresOff
Example: "6513d25b63cf07787018790a"
criticalitiesArray of objects(Criticality)

This parameter can modify criticality level of given rule.

processingLogIdstring(ProcessingLogId)

Processing log ID to which data should be upserted by worker. In the future, when processing log ID is provided, data is not upserted to job result storage.

Example: "VALIDATION_LOG"
processingLogTriggerstring(JobProcessingLogTriggerEnum)

Processing log trigger type determining way how the validation item or job has been triggered.

Enum ValueDescription
CREATED

Business partner has been created and monitoring is activated for his data source.

UPDATED

Business partner has been updated and monitoring is activated for his data source.

REFERENCE_DATA_CHANGED

Linked business partner has been updated.

REFRESHED

Validity span mechanism has been triggered or previous processing has failed.

INITIALIZED

Data monitor has been created or reactivated and business partner didn't have processing log results before.

CONFIGURATION_MODIFIED

Configuration has been modified for scope, where business partner is considered.

MANUALLY_FORCED

Processing of all business partners has been forced by customer.

MONITORING_REENABLED

Data monitor has been enabled from disabled and business partner already had processing log results before.

Example: "INITIALIZED"
vatAtRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "AT123456789"
vatDeRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "DE123456789"
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/businesspartnervalidationjobs \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "storageId": "YOUR_STORAGE_ID",
    "profile": "EU_VAT_QUALIFICATION",
    "featuresOn": [
      "SHOW_LOOKUP_RESULTS"
    ],
    "featuresOff": [
      "SHOW_LOOKUP_RESULTS"
    ],
    "ruleStatuses": [
      "RELEASED"
    ],
    "vatAtRequestor": "AT123456789",
    "vatDeRequestor": "DE123456789",
    "bzstPrint": true,
    "validationSource": "BZST",
    "reportsRequest": {
      "reportsConfiguration": {
        "address": {
          "build": false
        },
        "businesspartner": {
          "build": false
        },
        "identifier": {
          "build": false
        },
        "overall": {
          "build": false
        },
        "qualification": {
          "build": true
        },
        "qualityImprovement": {
          "build": false,
          "dataValidationJobIds": [
            "6be92567-4327-4463-813f-a8c990410d79",
            "f9df6cd4-4414-4719-9fb5-4eb6e5bc04cb"
          ]
        },
        "countryShortNames": "['\''PL'\'', '\''DE'\'', '\''CZ'\'', '\''SK'\'']"
      }
    },
    "dataSourcesOn": [
      {
        "prefix": "string"
      }
    ],
    "dataSourcesOff": [
      {
        "prefix": "string"
      }
    ],
    "ruleCategoriesOn": [
      {
        "url": "string",
        "name": "string"
      }
    ],
    "ignoredRules": [
      "string"
    ],
    "activatedRules": [
      "string"
    ],
    "updatedFrom": "2020-07-06T12:14:03.204Z",
    "dataSourceIds": [
      "string"
    ],
    "countryShortNames": [
      "string"
    ],
    "configurationId": "string",
    "criticalities": [
      {
        "businessRuleUrl": "string",
        "violationLevel": "NO_DEFECT"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
profilestring(ValidationProfile)

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

Enum ValueDescription
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"
featuresOnArray of strings

List of features to be activated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
featuresOffArray of strings

List to be deactivated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleStatusesArray of strings(RuleStatus)

Enable rules with provided statuses

Items Enum ValueDescription
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"]
jobDependenciesArray of objects(JobDependency)
labelsArray of objects(Label)
tagsArray of strings(JobTags)<= 12 items

List of tags.

Example: ["35f23c03-1c22-45fe-9484-3ffe769325de"]
bzstPrintstring

Request printed confirmation by German BZSt authority

Example: true
validationSourceobject(ValidationSource)

Source of the validation.

reportsRequestobject(ValidationReportsRequestParams)

Parameters for Validation Reports.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

ruleCategoriesOnArray of objects(RuleCategory)

List of rule categories that are used to filter rules by its category. If any value is present then only rules of given category will be promoted to execution.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
configurationIdstring(ConfigurationId)

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

  • profile
  • featuresOn
  • featuresOff
Example: "6513d25b63cf07787018790a"
criticalitiesArray of objects(Criticality)

This parameter can modify criticality level of given rule.

processingLogIdstring(ProcessingLogId)

Processing log ID to which data should be upserted by worker. In the future, when processing log ID is provided, data is not upserted to job result storage.

Example: "VALIDATION_LOG"
processingLogTriggerstring

Processing log trigger type determining way how the validation item or job has been triggered.

Enum ValueDescription
CREATED

Business partner has been created and monitoring is activated for his data source.

UPDATED

Business partner has been updated and monitoring is activated for his data source.

REFERENCE_DATA_CHANGED

Linked business partner has been updated.

REFRESHED

Validity span mechanism has been triggered or previous processing has failed.

INITIALIZED

Data monitor has been created or reactivated and business partner didn't have processing log results before.

CONFIGURATION_MODIFIED

Configuration has been modified for scope, where business partner is considered.

MANUALLY_FORCED

Processing of all business partners has been forced by customer.

MONITORING_REENABLED

Data monitor has been enabled from disabled and business partner already had processing log results before.

Example: "INITIALIZED"
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
statusstring(JobStatus)

Job execution status.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

ISO 8601 representation of the timestamp when the job was created.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(UserId)

Unique ID of a user.

Example: "johndoe"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
vatAtRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "AT123456789"
vatDeRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "DE123456789"
Response
application/json
{
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "profile": "QUICK",
  "featuresOn": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "featuresOff": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "ruleStatuses": [
    "RELEASED"
  ],
  "jobDependencies": [
    { … }
  ],
  "labels": [
    { … }
  ],
  "tags": [
    "35f23c03-1c22-45fe-9484-3ffe769325de"
  ],
  "vatAtRequestor": "AT123456789",
  "vatDeRequestor": "DE123456789",
  "bzstPrint": true,
  "validationSource": {
    "type": { … },
    "value": "CDL"
  },
  "reportsRequest": {
    "reportsConfiguration": { … },
    "labels": [ … ],
    "tags": [ … ]
  },
  "dataSourcesOn": [
    { … }
  ],
  "dataSourcesOff": [
    { … }
  ],
  "ruleCategoriesOn": [
    { … }
  ],
  "ignoredRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "activatedRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "updatedFrom": "2020-07-06T12:14:03.204Z",
  "dataSourceIds": [
    "648824a691d8d2503d65103e"
  ],
  "countryShortNames": [
    "CH"
  ],
  "configurationId": "6513d25b63cf07787018790a",
  "criticalities": [
    { … }
  ],
  "processingLogId": "VALIDATION_LOG",
  "processingLogTrigger": "INITIALIZED",
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "johndoe",
  "progress": "77"
}

List Business Partner Validation Batch Results

Request

Retrieve the results of a Business Partner validation job.

Security
basicAuth
Path
idstring(LookupJobId)required

ID of the Lookup Job.

Example: cbed7ac6-a97d-4c23-9060-2a88fa660957
Query
businessPartnerIdArray of strings(BusinessPartnerId)

Business Partner IDs which should be filtered.

Example: businessPartnerId=63e635235c06b7396330fe40
startAfterstring(StartAfter)

Only records with an ID greater than this ID will be fetched.

Example: startAfter=5712566172571652
limitinteger(Limit)

Number of results that should be fetched. Maximum 100 results can be returned in one page.

Example: limit=100
includeValidationResultFieldsArray of strings(ValidationResultField)

Include validation result fields.

Example: includeValidationResultFields=dataDefects
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/businesspartnervalidationjobs/cbed7ac6-a97d-4c23-9060-2a88fa660957/results \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(BusinessPartnerValidationResult)

List of validation results.

nextStartAfterstring(NextStartAfter)

Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
Response
application/json
{
  "startAfter": "5712566172571652",
  "limit": "100",
  "total": "67",
  "values": [
    { … }
  ],
  "nextStartAfter": "5712566172571652"
}

Poll Business Partner Validation JobDeprecated

Request

Allows polling the status of a Business Partner validation job.

Security
basicAuth
Path
idstring(DataValidationJobId)required

ID of the validation report.

Example: ef450653-a3bc-4476-83d3-d67397d475a0
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "johndoe")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/businesspartnervalidationjobs/ef450653-a3bc-4476-83d3-d67397d475a0 \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
profilestring(ValidationProfile)

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

Enum ValueDescription
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"
featuresOnArray of strings

List of features to be activated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
featuresOffArray of strings

List to be deactivated.

Items Enum ValueDescription
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).

ENRICH_CATEGORIES

Enrich a CDL community standardized business partner category for a given entity.

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.

IDENTIFIER_CHECKS

Validate business (VAT, tax, business register IDs) and location identifiers against different data quality rules categories.

Example: ["SHOW_LOOKUP_RESULTS"]
ruleStatusesArray of strings(RuleStatus)

Enable rules with provided statuses

Items Enum ValueDescription
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"]
jobDependenciesArray of objects(JobDependency)
labelsArray of objects(Label)
tagsArray of strings(JobTags)<= 12 items

List of tags.

Example: ["35f23c03-1c22-45fe-9484-3ffe769325de"]
bzstPrintstring

Request printed confirmation by German BZSt authority

Example: true
validationSourceobject(ValidationSource)

Source of the validation.

reportsRequestobject(ValidationReportsRequestParams)

Parameters for Validation Reports.

dataSourcesOnArray of objects(DataSource)

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

dataSourcesOffArray of objects(DataSource)

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

ruleCategoriesOnArray of objects(RuleCategory)

List of rule categories that are used to filter rules by its category. If any value is present then only rules of given category will be promoted to execution.

ignoredRulesArray 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))"]
activatedRulesArray 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))"]
updatedFromstring

Makes the job validate entries which were modified after given date described in ISO-8601 format.

Example: "2020-07-06T12:14:03.204Z"
dataSourceIdsArray of strings(BusinessPartnerStorageDataSourceId)

If set, only the records that belong to the data sources identified by these IDs are processed. By default, all records of the storage (means from all data sources) are processed (considering other filters).

Example: ["648824a691d8d2503d65103e"]
countryShortNamesArray of strings(CountryShortName)

If set, only the records that belong to the countries identified by these short names are processed. By default, all records of the storage (means from all countries) are processed (considering other filters).

Example: ["CH"]
configurationIdstring(ConfigurationId)

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

  • profile
  • featuresOn
  • featuresOff
Example: "6513d25b63cf07787018790a"
criticalitiesArray of objects(Criticality)

This parameter can modify criticality level of given rule.

processingLogIdstring(ProcessingLogId)

Processing log ID to which data should be upserted by worker. In the future, when processing log ID is provided, data is not upserted to job result storage.

Example: "VALIDATION_LOG"
processingLogTriggerstring

Processing log trigger type determining way how the validation item or job has been triggered.

Enum ValueDescription
CREATED

Business partner has been created and monitoring is activated for his data source.

UPDATED

Business partner has been updated and monitoring is activated for his data source.

REFERENCE_DATA_CHANGED

Linked business partner has been updated.

REFRESHED

Validity span mechanism has been triggered or previous processing has failed.

INITIALIZED

Data monitor has been created or reactivated and business partner didn't have processing log results before.

CONFIGURATION_MODIFIED

Configuration has been modified for scope, where business partner is considered.

MANUALLY_FORCED

Processing of all business partners has been forced by customer.

MONITORING_REENABLED

Data monitor has been enabled from disabled and business partner already had processing log results before.

Example: "INITIALIZED"
idstring(JobId)

Unique identifier of a job.

Example: "35f23c03-1c22-45fe-9484-3ffe769325de"
statusstring(JobStatus)

Job execution status.

Example: "RUNNING"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
startedAtstring

ISO 8601 representation of the timestamp when the job was created.

Example: "2019-08-31T16:47+00:00"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
userstring(UserId)

Unique ID of a user.

Example: "johndoe"
progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"
vatAtRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "AT123456789"
vatDeRequestorstringDeprecated

DEPRECATED, use organizational settings to configure.

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

Example: "DE123456789"
Response
application/json
{
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "profile": "QUICK",
  "featuresOn": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "featuresOff": [
    "SHOW_LOOKUP_RESULTS"
  ],
  "ruleStatuses": [
    "RELEASED"
  ],
  "jobDependencies": [
    { … }
  ],
  "labels": [
    { … }
  ],
  "tags": [
    "35f23c03-1c22-45fe-9484-3ffe769325de"
  ],
  "vatAtRequestor": "AT123456789",
  "vatDeRequestor": "DE123456789",
  "bzstPrint": true,
  "validationSource": {
    "type": { … },
    "value": "CDL"
  },
  "reportsRequest": {
    "reportsConfiguration": { … },
    "labels": [ … ],
    "tags": [ … ]
  },
  "dataSourcesOn": [
    { … }
  ],
  "dataSourcesOff": [
    { … }
  ],
  "ruleCategoriesOn": [
    { … }
  ],
  "ignoredRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "activatedRules": [
    "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
  ],
  "updatedFrom": "2020-07-06T12:14:03.204Z",
  "dataSourceIds": [
    "648824a691d8d2503d65103e"
  ],
  "countryShortNames": [
    "CH"
  ],
  "configurationId": "6513d25b63cf07787018790a",
  "criticalities": [
    { … }
  ],
  "processingLogId": "VALIDATION_LOG",
  "processingLogTrigger": "INITIALIZED",
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "status": "RUNNING",
  "createdAt": "2020-08-31T16:47+00:00",
  "startedAt": "2019-08-31T16:47+00:00",
  "finishedAt": "2020-08-31T16:47+00:00",
  "user": "johndoe",
  "progress": "77"
}

Business Partners

Provides funcionalities for managing Business Partners. Includes endpoints that allow users to validate Business Partners against data quality rules.

Operations

Configuration

Provides funcionalities for managing configurations. Includes endpoints that allow users to create, update, and delete configurations for the current user.

Operations

Public

Provides funcionalities to provide an RDF model of a record and validate a Business Partner.

Operations

Records

Provides funcionalities for managing records. Includes endpoints that allow users to validate records.

Operations

Processing Logs

Provides funcionalities for managing processing logs. Includes endpoints that allow users to read processing log results.

Operations