How to search for Business Partners?

Overview

Provides a comprehensive guide on how to activate data sources, create and test a configuration for the CDQ Lookup, and assign it to an API key for searching Business Partners.

Learning Goals

In this tutorial, the user will be focused on:

  • Activate data sources that can be searched
  • Create a configuration for the Lookup
  • Test the configuration and
  • Assign it to an API key

Step 1: Login

To set up and test the CDQ AML Guard, you have to log in to the CDQ Cloud Apps.

image01login

Click on Sign In and enter your username and password.

image02login

Step 2: Data Source Activation

CDQ is integrated with a variety of data sources, ranging from business and tax registers to commercial data providers such as D&B or Moody's. For a comprehensive list of all available data sources, please refer to a list of Data Sources.

Before these data sources can be used in CDQ products like the CDQ Lookup, they must be explicitly activated. This activation is a one-time process for the entire organization, and once completed, the activated data sources can be used across all workspaces.

To activate data sources:

  1. Navigate to the Global Settings app.

CDQLookup01

  1. Scroll down to the Reference Data Source Management section.
  2. Filter the results by typing the name of the data source you wish to activate in the Short name field.
  3. Additionally, filter by the country of origin or activation status, if necessary.
  4. Click the Settings button of the required data source to activate it.

CDQLookup02

attention

Please note that some data sources require authentication.

  1. Enter required credentials, tokens, or API keys in the data source's settings window.
  2. Set the status toggle to Active to activate the data source.

CDQLookup03

attention

Data sources are subject to quotas. Unlimited usage is not possible.

  1. To limit the requests to data sources, set the organization quota according to enterprise needs.
  2. Set the quota for the workspace if needed.
  3. Click Save settings to apply the changes.

CDQLookup04

Step 3: Creating a Configuration

The Lookup process requires the selection of a configuration. While the default configuration provided with the standard package can be used, there is also the flexibility to define custom configurations. This can be particularly useful if you wish to adjust matching score thresholds, consider specific data sources, or activate/deactivate features such as the golden record.

To create a new configuration, follow these steps:

  1. Navigate to the Augmentation Configurator app.

CDQLookup05

  1. Select Create new configuration button,

CDQLookup06

  1. Assign a distinctive name to your configuration,
  2. Click Create to save the configuration.

CDQLookup07

Data Sources Settings

  1. Click on the See details button to enter the settings of the newly created configuration.
  2. In the Reference Data Sources section, sellect all activated data sources that should be searched during the lookup process.
info

Refer to the Data Source Activation section for more details.

CDQLookup08

Lookup Settings

The Lookup settings tab provides access to more advanced settings, allowing you to fine-tune the behavior of the Lookup webservice.

  1. Navigate to the Lookup Settings tab.

CDQLookup09

  1. Configure the following options:
    • Matchnig Treshold,
    • Max candidates volume,
    • Page size,
Configuration Description
Matching score threshold Every search for company data yields a match with an associated overall matching score. The higher this score, the greater the confidence that the located record accurately represents the entity being searched for. By default, all matches with a score exceeding 0.5 are returned. A score of 0.5 implies a 50% confidence that the record is correct, and a 50% chance that the record pertains to a different entity. By increasing the threshold, you will receive fewer matches, but those that remain will have a higher confidence score.
Max number of matches (future, not available today) The search operation is designed to return a maximum number of potential matches as defined by you, even if there are more available. For instance, if there are potentially 50 matches, but you've set the maximum number to 10, only the top 10 matches will be displayed.
Expert configuration: number of candidates This configuration option necessitates a comprehensive understanding of the CDQ matching engine. It is advised to retain the default setting of 50 candidates. The matching engine operates in two stages. Initially, a set of candidates are identified through a broad, fuzzy search. Subsequently, matching scores are computed for these candidates.

Increasing the number of candidates inversely affects the performance of the lookup response time. For instance, if you set this number to 1000, a matching score will be calculated 1000 times for a single search. This is a complex operation that involves cleaners and advanced comparators.
Expert configuration: page size The page size is a configurable parameter within the API settings. It dictates the number of results that are returned per page in a paginated response. When an API request is made that yields a large number of results, the API may not provide all the results in a single response due to constraints on data transfer or processing. Instead, it may distribute the results across multiple pages, with each page containing a portion of the total results.

The 'pagesize' parameter gives you the ability to specify the number of results you wish to receive on each page of the response. By modifying the 'pagesize' parameter, you can manage the granularity of the data returned. This allows you to opt for more or fewer results per page, depending on the needs of your application. When an API request is made that yields a large number of results, the API may not provide all the results in a single response due to constraints on data transfer or processing. Instead, it may distribute the results across multiple pages, each containing a portion of the total results. The 'pagesize' parameter gives you the ability to specify the number of results you wish to receive on each page of the response. By modifying the 'pagesize' parameter, you can manage the granularity of the data returned, allowing you to opt for more or fewer results per page, depending on the needs of your application.
  1. Enable or disable the following features as needed:
Configurable features Description
ACTIVATE_IDENTIFIER_ONLY_MATCH Executes Lookup based only on an identifier. Company names and addresses will not affect results.
ENABLE_IDENTIFIER_DERIVATION Use fuzzy matching when searching with identifiers.
FORCE_EXTERNAL_CALL Call external service even when results from data mirrors are available.
SHOW_DEBUG_INFO Show additional information regarding request processing, including enabled features, requests, after the curation procedure and responses from external services.
SHOW_FORMATTED_ADDRESS Format addresses using data curation procedure.
SHOW_FORMATTED_SAP_RECORD Show formatted sap records in the lookup response.
SHOW_GOLDENRECORD_STANDARD Calculate the golden record for a given request.
GOLDENRECORD_INLINE Includes golden record at the first position in an array of values.
GOLDENRECORD_INLINE_SORTED Includes golden record in values array in response.
SHOW_INCOMPLETE_CANDIDATES Do not filter out search results without complete address data.
SHOW_SUBSCRIPTION_METADATA Provide information on whether the current user is subscribed to a given Business Partner, and overall subscription count.
  1. Click Save configuration to apply the changes.

Testing the Configuration

With the created configuration, the search for Business Partners can be performed. This configuration can be tested using the Business Partner Lookup application.

To search for Business Partner:

  1. Navigate to the Business Partner Lookup app,

CDQLookup10

  1. Select the Settings button,
  2. Set the configuration created in the previous steps in the Augmentation/BP Lookup Configuration field,
  3. Click Save changes to apply the changes.

CDQLookup11

  1. Enter the search criteria:
Copy
Copied
Name: `CDQ AG`
Country: `CH - Switzerland`
Identifier: `CH32030769341`
info

The more detailed the information you provide, the more accurate the lookup results will be. At a minimum, a name and a country or one business identifier should be provided.

In general, the following attributes can be used for the search:

Attribute Description
Name The Business Partner‘s name
Country The country of the Business Partner’s address
Street The street of the Business Partner’s address
City The city of the Business Partner’s address
Postcode The postcode of the Business Partner’s address
Identifier + type A business identifier such as European VAT numbers or business register IDs. The type of the given identifier can be selected from the dropdown

CDQLookup12

  1. Click Lookup button to initiate the search process based on your input and the specified configuration.

The result list will provide multiple Business Partner records that match the search criteria. If the golden record feature is activated and the matching engine can generate one, a golden record is also included in the results.

info

The golden record is a single, consolidated view of the Business Partner that is considered the most accurate representation of the entity.

Step 4: Creating an API key

info

For details on how to create and set an API key see these instructions: Authentication

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