# 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. | | | --- | | ![](/assets/ftr-overview.ecaf4c86a02ec70c8b6200adaad9ff4b03cf563df1fa85ce6bb10360524e19cd.cbb72118.png) | | *Use Case: Situation, Approach and Results* | A complete use case description is available on the [Wiki](https://meta.cdq.com/Use_case/business_partner_data_maintenance_workflow). **Learning Goals** | | | --- | | ![](/assets/processchart.b9b6e2c6140486955440a89888bf248f32d0d49c0d0df6738c192620e76d9e33.cbb72118.png) | | *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 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. ![](/assets/auth7.0d4fb05fa55bc16d828c76e9976f979930ffadb949cfc149a6617cc6518ab57d.6fde6558.png) 1. After pasting the API Key, the green padlock will appear. ![](/assets/auth8.28e02515b78db57ec32c07fd6bd7d296484e64f65ef6a3bc5296520cb1da8d65.6fde6558.png) 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](/documentation/instructions/authentication). 2. Follow the steps above. ### Business Partner data Business Partner chosen for the tutorials: | Name | Localities | Thoroughfares | PL VAT ID | | --- | --- | --- | --- | | `SWISS KRONO Sp. z o.o.` | `Żary` | `Serbska 56` | `PL9280012700` | ### Data Source activation. Remember to activate a VIES data source and accept terms of conditions before you start the tutorial. To activate it use [Global Settings](https://apps.cdq.com/dashboard/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: 2. Check the above example in the **Try It Console** now: 1. Check the response. `"SWISS KRONO Sp. z o.o."` is presented in the `VIES:PL9280012700` data pool. Make sure all required data sources are enabled. All data sources are listed in the feature table [here](https://developer.cdq.com/reference-docs/reference-data/V3/tag/Business-Partners/#tag/Business-Partners/paths/~1v3~1businesspartners~1lookup/post). 1. Check the `matchingProfile` in the response and find `matchingScores` value for Business Partner reliability. ```json { "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](https://meta.cdq.com/Field/Business_Partner_Matching_Score) or [Match Classification](https://meta.cdq.com/Field/Business_Partner_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. 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. All features included in the `STANDARD` profile are described in this [page](https://meta.cdq.com/API/Data_Curation_API/Profile/STANDARD). To enrich given Business Partner data: 1. Use the **Business Partner Curate** endpoint to send below request: 2. Check the above example in the **Try It Console** now: 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. ```json { "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. ```json { "curationAnalysis":{ "requestSimilarity":{}, "curationLevel": "LEVEL_6", "accuracyIndicator": 3, "outputLanguage": "EN", "curationDecision":{}, "geographicCoordinatesAccuracy": "THOROUGHFARE_NUMBER" } } ``` 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: 2. Check the above example in the **Try It Console** now: 1. Check the response above and check the `validatorMessage` for value. ```json { "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. 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: 2. Check the above example in the **Try It Console** now: An additional `"businessPartner"` object appeared in the response with Business Partner data. ```json { "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!