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

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

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

Read Processing Log Results

Request

Retrieves latest data curation results persisted in Processing Log.

Data is populated only when Data Monitor is configured for provided storage.

Security

basicAuth

Path

storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6

Query

processingLogIdstring(ValidationProcessingLogIdParam)required

Processing log id with acceptable values:

VALIDATION_LOG
VALIDATION_SHARING_LOG VALIDATION_LOG is default value.

Default "VALIDATION_LOG"

Enum Value	Description
VALIDATION_LOG	Validation log id for validation results.
VALIDATION_SHARING_LOG	Validation log id for sharing validation results.

Example: processingLogId=VALIDATION_LOG

businessPartnerIdArray of strings(BusinessPartnerId)<= 500 items

Business Partner IDs which should be filtered.

Example: businessPartnerId=63e635235c06b7396330fe40

dataSourceIdstring(BusinessPartnerStorageDataSourceId)

Data Source ID.

Example: dataSourceId=648824a691d8d2503d65103e

externalIdArray of strings(BusinessPartnerExternalId)<= 500 items

Business Partner external IDs.

Example: externalId=The ID managed in the customer's SAP systems.

processingStatusTechnicalKeystring(ProcessingStatusTechnicalKeyEnum)

Processing status technical key.

Enum Value	Description
READY	Processing Log Data processing has finished and result ready to consume.
RETRY	Processing Log Data processing has failed and needs to be retried.
BLOCKED	Processing Log Data processing is blocked and needs to be resolved.
IN_PROGRESS	Processing Log Data is being processed.

Example: processingStatusTechnicalKey=IN_PROGRESS

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

fromstring

ISO 8601 representation of the timestamp when the result data was created.

Example: from=2020-08-31T16:47+00:00

tostring

ISO 8601 representation of the timestamp when the result data was created.

Example: to=2020-08-31T16:47+00:00

featuresOffArray of strings(ValidationLogResultsReadFeatureEnum)

Feature(s) to not use during reading the results (INTERNAL ONLY):

FETCH_RESULT_DATA - Don’t return result data, only result metadata.
NUMBER_OF_TOTAL - Don’t return total.

Items Enum Value	Description
FETCH_RESULT_DATA	Fetch result data.
NUMBER_OF_TOTAL	Number of totals.

Example: featuresOff=FETCH_RESULT_DATA

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/validationlogs/72d6900fce6b326088f5d9d91049e3e6/results?processingLogId=VALIDATION_LOG' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

Bodyapplication/json

startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"

nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"

limitinteger(Limit)

Number of items per page.

Example: "100"

fromstring

ISO 8601 representation of the timestamp when the result data was created.

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

tostring

ISO 8601 representation of the timestamp when the result data was created.

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

totalinteger(int32)

Total number of validation log entries.

Example: "20"

valuesArray of objects(ValidationProcessingLogResult)

List of validation log entries.

Response

application/json

{
  "startAfter": "5712566172571652",
  "nextStartAfter": "5712566172571652",
  "limit": "100",
  "from": "2020-08-31T16:47+00:00",
  "to": "2020-08-31T16:47+00:00",
  "total": "20",
  "values": [
    { … }
  ]
}

Upload Processing Logs

Request

Uploads processing logs to CDQ. The processing logs are used to improve the quality of the data curation results.

Security

basicAuth

Path

storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6

Query

processingLogIdstring(ValidationProcessingLogIdParam)required

Processing log id with acceptable values:

VALIDATION_LOG
VALIDATION_SHARING_LOG VALIDATION_LOG is default value.

Default "VALIDATION_LOG"

Enum Value	Description
VALIDATION_LOG	Validation log id for validation results.
VALIDATION_SHARING_LOG	Validation log id for sharing validation results.

Example: processingLogId=VALIDATION_LOG

featuresOnArray of strings(ValidationProcessingLogFeatureParam)

Features to be used during uploading processing logs.

Items Value"LAB_USE_QUEUES"

Example: featuresOn=LAB_USE_QUEUES

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

resultsArray of objects(ValidationProcessingLogResult)required

List of Validation Processing Log Results.

results[].dataSourceIdstring(StorageDataSourceId)

Unique number of Data Source.

Example: "5e2874fb8d2a7400011acee1"

results[].businessPartnerIdstring(BusinessPartnerId)

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"

results[].addressIdstring

ID of the address in the storage or data mirror.

Example: "123456789"

results[].externalIdstring(BusinessPartnerExternalId)

Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.

Example: "The ID managed in the customer's SAP systems."

results[].addressExternalIdstring(AddressExternalId)

ID the address has in the external system where the record originates from.

Example: "1"

results[].statusstring

Can be OK or FAILED - default is OK.

Default "OK"

Example: "OK"

results[].processingStatusobject(ProcessingStatus)

Processing status.

results[].messagestring

Additional explanations for status - especially for the FAILED case.

Example: "Validation failed"

results[].validationResultobject(BusinessPartnerValidationResult)

Validation result for a single Business Partner.

results[].executedAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

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

curl -i -X PUT \
  -u <username>:<password> \
  'https://idp.cdq.com/_mock/apis/data-validation-api/api-v3/v2/validationlogs/72d6900fce6b326088f5d9d91049e3e6/results?processingLogId=VALIDATION_LOG' \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "results": [
      {
        "dataSourceId": "5e2874fb8d2a7400011acee1",
        "businessPartnerId": "63e635235c06b7396330fe40",
        "addressId": "123456789",
        "externalId": "The ID managed in the customer'\''s SAP systems.",
        "addressExternalId": "1",
        "status": "OK",
        "processingStatus": {
          "technicalKey": "IN_PROGRESS",
          "modifiedAt": "2020-08-31T16:47+00:00"
        },
        "message": "Validation failed",
        "validationResult": {
          "dataDefects": [
            {
              "validationSource": {
                "type": {},
                "value": "CDL"
              },
              "businessRule": {
                "name": "Identifier unknown (European value added tax identifier (The Netherlands))",
                "url": "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))",
                "ruleStatus": "RELEASED",
                "violationMessage": "Business Partner identifier is mandatory.",
                "violationLevel": "INFO"
              },
              "executionContextProperties": [
                {}
              ],
              "categories": [
                {}
              ]
            }
          ],
          "qualificationResult": {
            "sourceData": [
              {
                "key": "addrz1",
                "value": "CH-9000"
              }
            ],
            "formattedSourceData": {
              "code": "ATU12345678",
              "message": "Message to be filled in.",
              "businessPartnerName": "Muster AG",
              "postCodeValue": "9000",
              "thoroughfareValue": "Hauptstrasse",
              "localityValue": "München"
            },
            "validatorStatus": "ONLINE",
            "validatorMessage": "VAT ID is valid.",
            "qualifiedBy": {
              "type": {
                "technicalKey": "VALIDATION_GRAPH",
                "description": "Default CDL Model"
              },
              "value": "CDL"
            },
            "qualifiedAt": "2019-07-11T16:32:28.425",
            "addressQualification": "QUALIFIED",
            "addressQualificationDetails": {
              "localityQualification": "QUALIFIED",
              "postCodeQualification": "QUALIFIED",
              "thoroughfareNumberQualification": "QUALIFIED",
              "thoroughfareQualification": "QUALIFIED"
            },
            "identifierValidity": "VALID",
            "businessPartnerNameQualification": "QUALIFIED",
            "overallQualification": "QUALIFIED"
          },
          "lookupResults": [
            {
              "businessPartner": {
                "id": "63e635235c06b7396330fe40",
                "dataSource": "Internal customers",
                "externalId": "The ID managed in the customer'\''s SAP systems.",
                "addresses": [
                  null
                ],
                "names": [
                  null
                ],
                "identifiers": [
                  null
                ],
                "legalForm": "Aktiengesellschaft",
                "bankAccounts": [
                  null
                ],
                "status": {},
                "profile": {
                  "contactEmails": []
                }
              },
              "address": "Lukasstraße 4, 9008 St. Gallen",
              "matchingScore": "0.9",
              "dataSource": "648824a691d8d2503d65103e",
              "cdqId": "VIES:DE119267630"
            }
          ],
          "summary": {
            "validationLevel": "ERROR",
            "dataQualityRecordStatus": {
              "name": "No issues found",
              "description": "All rules have been executed, and we have found no data quality issues.",
              "technicalKey": "NO_ISSUES_FOUND"
            },
            "action": "FULL_CHECK",
            "statistics": {
              "numberOfInfoDataDefects": "10",
              "numberOfErrorDataDefects": "10",
              "numberOfWarningDataDefects": "10"
            }
          },
          "debugInfo": {
            "externalServiceResponses": [
              {
                "status": "200",
                "message": "There is no more quota left for this Data Source.",
                "path": "/data-validation/businesspartners/validate",
                "details": "Detailed message",
                "timestamp": "2019-07-11T16:32:28.425",
                "additionalInformation": [
                  null
                ]
              }
            ],
            "businessRulesExecutionSummary": {
              "numberOfRules": "274",
              "numberOfExecutions": "273",
              "numberOfFails": "1",
              "failures": [
                {}
              ],
              "warnings": [
                {}
              ],
              "dataSourcesOn": [
                {}
              ],
              "dataSourcesOff": [
                {}
              ],
              "activatedRules": [
                "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
              ],
              "ignoredRules": [
                "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))"
              ],
              "ruleCategoriesOn": [
                {}
              ],
              "ruleStatuses": [
                "RELEASED"
              ],
              "violationLevels": [
                "INFO"
              ]
            }
          },
          "identifierResults": [
            {
              "property": {
                "value": "DE119267630",
                "type": "EU_VAT_ID_DE"
              },
              "reliabilityLevel": {
                "name": "Identifier existence",
                "url": "https://meta.cdq.com/Identifier_existence",
                "value": "4",
                "checks": [
                  null
                ]
              },
              "qualificationDecisions": [
                {
                  "properties": []
                }
              ]
            }
          ],
          "businessPartner": {
            "names": [
              "Corporate Data Quality AG"
            ],
            "legalForm": "Aktiengesellschaft",
            "identifiers": [
              "VAT identification number"
            ],
            "categories": [
              "Hotel"
            ],
            "status": {
              "officialDenotation": "Good Standing",
              "validFrom": "2022-02-26",
              "validUntil": "2022-02-26",
              "type": "In Liquidation"
            },
            "addresses": [
              "Lukasstraße 4, 9008 St. Gallen"
            ],
            "externalId": "The ID managed in the customer'\''s SAP systems.",
            "profile": {
              "contactEmails": [
                "developer-portal@cdq.com"
              ]
            },
            "formattedSapRecord": {
              "name1": "CDQ AG",
              "name2": "CDQ AG",
              "name3": "CDQ AG",
              "name4": "CDQ AG",
              "nameCo": "Aktiengesellschaft",
              "legalEntity": "Aktiengesellschaft",
              "legalForm": "Aktiengesellschaft",
              "indSector": "NAF",
              "narp": "Friedrich Nietzsche",
              "stceg": "CHE-218.608.88",
              "stcd1": "CHE-218.608.88",
              "stcd2": "CHE-218.608.88",
              "stcd3": "CHE-218.608.88",
              "stcd4": "CHE-218.608.88",
              "stcd5": "CHE-218.608.88",
              "url": "www.cdq.com",
              "telNumber": "+41 71 571 10 40",
              "country": "Switzerland",
              "countryCode": "CH",
              "region": "Sankt Gallen",
              "regionCodeSap": "9004",
              "regionCode": "9004",
              "county": "Sankt Gallen",
              "countyCode": "9004",
              "township": "Sankt Gallen",
              "townshipCode": "9004",
              "city": "Sankt Gallen",
              "district": "St. Georgen",
              "postalCode": "9000",
              "postalCode3": "9000",
              "street1": "Lukasstraße 4",
              "street2": "Lukasstraße 4",
              "street5": "Lukasstraße 4",
              "houseNum": "4",
              "houseNum2": "4",
              "building": "Office 2",
              "floor": "2",
              "roomnumber": "123",
              "poBoxCountry": "9000",
              "poBoxCity": "9000",
              "poBoxPostalCode": "9000",
              "poBox": "9000",
              "latitude": "47.439549",
              "longitude": "9.395275"
            },
            "relations": [
              "Commercial ultimate"
            ],
            "bankAccounts": [
              {
                "internationalBankAccountIdentifier": "CH8800781619278412000",
                "internationalBankIdentifier": "KBSGCH22XXX",
                "nationalBankAccountIdentifier": "619278412000",
                "nationalBankIdentifier": "00781",
                "bank": {},
                "countryCode": "DE"
              }
            ],
            "types": [
              {
                "name": "Legal Entity",
                "url": "https://meta.cdq.com/Business_partner/type",
                "technicalKey": "LEGAL_ENTITY"
              }
            ],
            "externalContext": "LIFNR",
            "id": "63e635235c06b7396330fe40",
            "dataSource": "VIES",
            "lastModifiedAt": "2020-08-31T16:47+00:00"
          },
          "rulesInError": [
            {
              "businessRule": {
                "name": "Identifier unknown (European value added tax identifier (The Netherlands))",
                "url": "https://meta.cdq.com/Identifier_unknown_(European_value_added_tax_identifier_(The_Netherlands))",
                "ruleStatus": "RELEASED"
              },
              "executionStatus": "500",
              "error": {
                "timestamp": "2019-08-31T16:47+00:00",
                "message": "This user is not allowed to access this service.",
                "error": "BAD_REQUEST",
                "path": "/v2/businesspartners/lookup",
                "status": "400",
                "id": "REF_VIES_SERVICE_UNAVAILABLE_300"
              },
              "ruleResult": "parentConceptIdSelector = '\''businessPartner.identifiers.technicalKey'\'', content = '\''1633582012931231'\'', parentConceptUrl='\''https://meta.cdq.com/Business_partner/identifier'\'', recordId = '\''451ff2f9-8182-43fc-9728-aad9ce62d771'\'', contentSelector = '\''businessPartner.identifiers.value'\'', contentSelectorUrl = '\''https://meta.cdq.com/Business_partner/identifier/value'\'', parentConceptId = '\''EE_BRN'\''",
              "violationLevel": "INFO",
              "validationSource": "CDQ"
            }
          ],
          "executedAt": "2019-09-07T00:00:00Z"
        },
        "executedAt": "2020-08-31T16:47+00:00"
      }
    ]
  }'

Responses

Bodyapplication/json

upsertedinteger(int32)

Number of upserted validation log entries.

Example: "20"

failedinteger(in32)

Number of failed validation log entries.

Example: "0"

Response

application/json

{
  "upserted": "20",
  "failed": "0"
}

Data Validation API (3)

Qualification

Validation

Batch Validation

Business Partners

Configuration

Public

Records

Processing Logs

Read Processing Log Results

Request

Responses

Share the feedback!

Upload Processing Logs

Request

Responses

Share the feedback!

Data Validation API (3)

Qualification

Validation

Batch Validation

Business Partners

Configuration

Public

Records

Processing Logs

Read Processing Log Results

Request

Responses

Share the feedback!

Upload Processing Logs

RequestExpand all

Responses

Share the feedback!

Request