CDQ Insights API - Getting Started - Exploring the Catalogue

Copy

Overview

The CDQ Insights API gives you programmatic access to pre-calculated metrics about your business partner data. Instead of building your own queries or waiting for a report, you send a request and receive ready-to-use numbers (counts, ratios, and trends) calculated directly from your CDQ Data Mirror.

The API has two endpoints:

• The catalogue endpoint tells you what metrics are available and how to request them.
• The data endpoint returns the actual metric values for your chosen time range, filters, and groupings.

This tutorial focuses on the catalogue. Subsequent tutorials cover how to fetch and work with data. No technical setup is required for this tutorial.

Learning Goals

In this tutorial, you will learn how to:

• Understand what the CDQ Insights API is and what it returns
• Read how the metric catalogue is organized into categories
• Interpret an insight definition to find the right metric for your business question
• Tell the difference between count (sum) and ratio metrics, and between workspace and organization scope

How the catalogue is organized

All metrics are grouped into categories. Each category covers a specific domain of your business partner data:

Within each category you will find individual metrics, each with a unique identifier called an id. This id is what you use when requesting data.

Anatomy of an insight definition

Every metric in the catalogue follows the same structure. Here is the validated_records metric as an example:

{
  "id": "validated_records",
  "name": "Validated Records",
  "description": "The total number of validated records.",
  "category": "data_quality",
  "useCases": [
    "Monitor the volume of validated records over time.",
    "Analyze validation results by violation level, source, and country."
  ],
  "calculation": {
    "formula": "SUM(\"_value\")",
    "level": "workspace",
    "resultDefinition": "For the selected scope, sums up total records.",
    "resultType": "sum",
    "dataTypes": ["number"]
  },
  "dimensions": [
    { "name": "country", "description": "The country short name of the business partner." },
    { "name": "dataSourceId", "description": "A unique identifier of the data source." },
    { "name": "violationLevel", "description": "Violation level assigned to the detected defect." }
  ],
  "options": [
    { "name": "topNCountriesByBusinessPartnerCount", "description": "Limits results to top N countries ranked by business partner count." }
  ],
  "filtersSupported": ["country", "dataSourceId", "violationLevel"],
  "type": "public"
}

Let's walk through each field.

id

The unique identifier for this metric. This is what you include in your data request. Always lowercase, using underscores. Example: validated_records.

name and description

A human-readable label and a plain-language explanation of what the metric measures.

category

The domain this metric belongs to. Useful for browsing the catalogue when you are not sure which metric you need.

useCases

A list of business questions this metric can help answer. If one of these matches your question, you have found the right metric.

calculation

This section explains how the number is computed:

• resultType: either sum (a count or total) or ratio (a proportion between 0 and 1). Knowing this tells you how to interpret the value you receive.
• level: either workspace or organization. Most metrics are workspace-scoped, meaning results are calculated within your specific workspace. Organization-scoped metrics aggregate across all workspaces in your organization.
• resultDefinition: a plain-language explanation of what the formula actually produces.

dimensions

Dimensions let you break down a metric. For example, adding country as a dimension means the API returns a separate value for each country rather than a single total. You can combine multiple dimensions in one request.

filtersSupported

Filters let you narrow the data before the metric is calculated. For example, filtering by country = DE means only German records are included in the result. The fields listed here are the ones you are allowed to filter on for this specific metric.

options

Optional modifiers that change how the metric is calculated or what data is returned. The most common option is topNCountriesByBusinessPartnerCount, which limits results to the top N countries ranked by how many business partners they have. This is useful when you want a focused view rather than the full global breakdown.

Count vs ratio: knowing what you are looking at

Understanding resultType is important because it changes how you read and use the value:

• A sum metric returns a whole number, a count of records, cases, or events. For example, validated_records returning 4617 means there are 4,617 validated records in your workspace for that period.
• A ratio metric returns a decimal between 0 and 1, representing a proportion. For example, data_quality_ratio returning 0.94 means 94% of validated records are free from critical defects.

Workspace vs organization scope

Most metrics are calculated at workspace level, meaning results reflect the data in a specific CDQ workspace. If your organization has multiple workspaces, each one is reported independently.

A small number of metrics, primarily in the bank_accounts category, are calculated at organization level, aggregating data across all workspaces in your organization. The level field in the calculation object tells you which applies.

Finding the right metric for your question

The fastest way to find a metric is to look at the useCases list. Here are a few examples of business questions mapped to the metrics that answer them:

Next steps

Now that you understand the catalogue, the Fetching a Metric with Postman tutorial walks you through making your first data request, fetching a real metric value for a date range in just a few clicks.

Your opinion matters!

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