Tutorial: CDQ First Time Right

Overview

Use case

This tutorial describes the recommended use of CDQ Cloud Platform APIs for maintaining a single business partner data record. The presented flow provides the most comprehensive use of features and explains the API endpoints to be used.

ftr overview
Use Case: Situation, Approach and Results
info

A complete use case description is available on the Wiki.

Learning Goals

ProcessChart
Common Process and involved APIs/Endpoints

In this tutorial, you will learn how:

  1. Verify Business Partner existence in one of the public pools (VIES) with the help of the CDQ reference data.
  2. Enrich existing data
  3. Verify data quality before storing
attention

The following tutorial describes a happy path based on a common use case. Depending on your particular business requirements, the steps may be different and/or need to be customized.

Prerequisites

Authorization

Before trying CDQ APIs, user must be authenticated:

  1. Paste the API Key in the console's security bar into the X-API-KEY field.
auth7
  1. After pasting the API Key, the green padlock will appear.
auth8
Be careful

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

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

No API Key?

  1. Check how to get one on authentication page.
  2. Follow the steps above.

Business Partner data

Business Partner chosen for the tutorials:

NameLocalitiesThoroughfaresPL VAT ID
SWISS KRONO Sp. z o.o.ŻarySerbska 56PL9280012700

Data Source activation.

Remember to activate a VIES data source and accept terms of conditions before you start the tutorial.

info

To activate it use Global Settings app.

Step 1 Data Pool Lookup and Record Selection

To verify given Business Partner in the VIES public data pool:
  1. Use the Business Partner Lookup endpoint to send below request:
application/json
{
  • "matchingThreshold": 0,
  • "pageSize": 10,
  • "page": 0,
  • "dataSources": [
    • "string"
    ],
  • "businessPartner": {
    • "names": [
      • {
        • "value": "SWISS KRONO SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ"
        }
      ],
    • "identifiers": [
      • {
        • "value": "string",
        • "type": {
          • "technicalKey": "string"
          }
        }
      ],
    • "legalForm": {
      • "value": "string"
      },
    • "addresses": [
      • {
        • "thoroughfares": [
          • {
            • "value": "Serbska",
            • "number": "56"
            }
          ],
        • "localities": [
          • {
            • "value": "Żary"
            }
          ],
        • "administrativeAreas": [
          • {
            • "value": "string"
            }
          ],
        • "postCodes": [
          • {
            • "value": "string"
            }
          ],
        • "country": {
          • "shortName": "PL"
          }
        }
      ]
    },
  • "featuresOn": [
    • "ACTIVATE_DATASOURCE_CDQ_POOL"
    ]
}
  1. Check the above example in the Try It Console now:
Loading...
  1. Check the response. "SWISS KRONO Sp. z o.o." is presented in the VIES:PL9280012700 data pool.
info

Make sure all required data sources are enabled. All data sources are listed in the feature table here.

  1. Check the matchingProfile in the response and find matchingScores value for Business Partner reliability.
Copy
Copied
{
    "matchingProfile":{
        "matchingScores":{
            "overall":{
                "classification":{
                    "technicalKey": "FULL_MATCH",
                    "name": "Full Match"
                },
                "value": 0.9928821602078861,
                "explanation": "BP: [overall: [NAME: 0.91; overall: 0.91;]] A: [overall: [LOCALITY: 0.65; overall: 0.65; THOROUGHFARE: 0.8; overall: 0.8813559322033899; THOROUGHFARE_NUMBER: 0.65; overall: 0.9324137931034483;]]"
            },
            "businessPartner":{},
            "address":{}
        }
    }
}
A matchingScores above 0,88 generally indicates a great lookup result. Visit Wiki for more information about Matching Score or Match Classification.In the presented case the classification shows FULL_MATCH and the matchScores value equals 0.9928821602078861 which means the provided Business Partner data are aligned with CDQ records.
success

Your Business Partner is verified in the CDQ repository! Go to the next step.

Step 2 Address Cleansing

In this step, the user can perform activities to enrich desired data. During usage of Business Partner Curate, the STANDARD profile is active by default.
info
All features included in the STANDARD profile are described in this page.

To enrich given Business Partner data:

  1. Use the Business Partner Curate endpoint to send below request:
application/json
{
  • "businessPartner": {
    • "names": [
      • {
        • "value": "SWISS KRONO Sp. z o.o.",
        • "type": {
          • "technicalKey": "INTERNATIONAL"
          }
        }
      ],
    • "addresses": [
      • {
        • "country": {
          • "shortName": "PL"
          },
        • "localities": [
          • {
            • "value": "Żary"
            }
          ],
        • "thoroughfares": [
          • {
            • "value": "Serbska",
            • "number": "56"
            }
          ]
        }
      ]
    }
}
  1. Check the above example in the Try It Console now:
Loading...
  1. Request can be different from the one visible on the user screen and be collapsed (if you are using the developer portal console).
  2. Check the addressCurationResults to see enriched data with detailed administrative area information, post-code and geographic coordinates.
Copy
Copied
{
    "addressCurationResults": [
      {
        "curatedAddress": {
            "version": {},
            "metadata": {},
            "country":
              {
                "shortName": "PL",
                "value": "Poland"
              },
            "administrativeAreas":[
              {
                "value": "Lubusz Voivodeship",
                "shortName": "08",
                "type":{}
              },
              {
                "value": "Powiat Żarski",
                "shortName": "Powiat Żarski"
              }
            ],
            "postCodes":[
              {
                "value": "68-200",
                "type":{}
              }
            ],
            "localities": [],
            "thoroughfares": [],
            "geographicCoordinates":{
                "latitude": 51.63314,
                "longitude": 15.10538
            }
        }
      }
    ]
}
  1. Check the curationAnalysis to find important indicator curationLevel which shows LEVEL_6 value. It means that enriched data is validated.
Copy
Copied
{
    "curationAnalysis":{
        "requestSimilarity":{},
        "curationLevel": "LEVEL_6",
        "accuracyIndicator": 3,
        "outputLanguage": "EN",
        "curationDecision":{},
        "geographicCoordinatesAccuracy": "THOROUGHFARE_NUMBER"
      }
}
success

Your Business Partner data are enriched! Go to the next step!

Step 3 Data Quality Check

Identifier Qualification

Qualification is the most powerful data quality check for identifiers. It does not only check the format and general registration of a tax number but compared given name and address data to the authority record of the given tax number. With a qualified tax number (i.e., a qualified tax number/name/address combination), you have proof that your data is equal to the particular authority's registry.

To validate given Business Partner data:

  1. Use the Business Partner Validate endpoint to send below request:
application/json
{
  • "businessPartner": {
    • "names": [
      • {
        • "value": "SWISS KRONO Sp. z o.o."
        }
      ],
    • "identifiers": [
      • {
        • "value": "PL9280012700",
        • "type": {
          • "technicalKey": "EU_VAT_ID_PL"
          }
        }
      ],
    • "legalForm": {
      • "name": "Spółka z ograniczoną odpowiedzialnością"
      },
    • "addresses": [
      • {
        • "country": {
          • "shortName": "CH"
          },
        • "thoroughfares": [
          • {
            • "value": "Lukasstrassse 4"
            }
          ],
        • "localities": [
          • {
            • "value": "St.Gallen"
            }
          ],
        • "postCodes": [
          • {
            • "value": "9008"
            }
          ]
        }
      ]
    },
  • "profile": "QUALIFICATION",
  • "featuresOn": [
    • "SHOW_QUALIFICATION"
    ],
  • "addresses": [
    • {
      • "country": {
        • "shortName": "PL"
        },
      • "thoroughfare": {
        • "value": "Serbska 56"
        },
      • "locality": {
        • "value": "Żary"
        },
      • "postCode": {
        • "value": "68-200"
        }
      }
    ]
}
  1. Check the above example in the Try It Console now:
Loading...
  1. Check the response above and check the validatorMessage for value.
Copy
Copied
{
        "validatorMessage": "VAT ID is valid."
}
The message in the request body: "VAT ID is valid." confirms the reliability of the VAT identifier of the Business Partner.
attention
Not all examples shows the validatorMessage in the response. Add "featuresOn": ["SHOW_QUALIFICATION"] to the body to see it.

Additional quality checks

To perform additional checks below feature send the request without any profile on, the STANDARD profile will be activated by default.

To validate given Business Partner data:

  1. Use the Business Partner Validate endpoint to send below request:
application/json
{
  • "businessPartner": {
    • "names": [
      • {
        • "value": "SWISS KRONO Sp. z o.o."
        }
      ],
    • "identifiers": [
      • {
        • "value": "PL9280012700",
        • "type": {
          • "technicalKey": "EU_VAT_ID_PL"
          }
        },
      • {
        • "value": "9280012700",
        • "type": {
          • "technicalKey": "PL_NIP"
          }
        },
      • {
        • "value": "970327738",
        • "type": {
          • "technicalKey": "PL_REG"
          }
        }
      ],
    • "legalForm": {
      • "name": "Spółka z ograniczoną odpowiedzialnością"
      },
    • "addresses": [
      • {
        • "country": {
          • "shortName": "PL"
          },
        • "thoroughfares": [
          • {
            • "value": "Serbska 56"
            }
          ],
        • "localities": [
          • {
            • "value": "Żary"
            }
          ],
        • "postCodes": [
          • {
            • "value": "68-200"
            }
          ],
        • "administrativeAreas": [
          • {
            • "value": "lubuskie"
            }
          ]
        }
      ]
    }
}
  1. Check the above example in the Try It Console now:
Loading...
An additional "businessPartner" object appeared in the response with Business Partner data.
Copy
Copied
{
    "summary":{
        "validationLevel": "NO_DEFECTS",
        "action": "AUTO_APPROVE",
        "statistics": {}
    },
    "debugInfo":
    {
        "businessRulesExecutionSummary":{}
    },
    "identifierResults":[
    {
        "property":{
            "value": "PL9280012700",
            "type": "EU_VAT_ID_PL"
        },
        "reliabilityLevel":{
            "name": "Identifier existence",
            "url": "https://meta.cdq.com/Identifier_existence",
            "value": 4,
            "checks":[]
        }
    },
    {
        "property":{
            "value": "9280012700",
            "type": "PL_NIP"
        },
        "reliabilityLevel":{
            "name": "Identifier existence",
            "url": "https://meta.cdq.com/Identifier_existence",
            "value": 4,
            "checks":[]
        }
    },
    {
        "property":{
            "value": "970327738",
            "type": "PL_REG"
        },
        "reliabilityLevel":{
            "name": "Identifier existence",
            "url": "https://meta.cdq.com/Identifier_existence",
            "value": 4,
            "checks":[]
        }
    }
    ],
    "businessPartner":{
        "names":[],
        "legalForm":{},
        "identifiers":[],
        "addresses":[
        {
            "country":{
                "shortName": "PL",
                "value": "Poland"
            },
            "administrativeAreas":[
            {
                "value": "lubuskie"
            }
            ],
            "postCodes":[
            {
                "value": "68-200"
            }
            ],
            "localities":[
            {
                "value": "Żary"
            }
            ],
            "thoroughfares":[
            {
                "value": "Serbska 56"
            }
            ]
        }
        ]
    }
}
Congratulations!

Your Business Partner data are validated!

Step 4 Data ready to store

After performing all the above steps, the Business Partner data can be stored in the corporate database.

Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!

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