# CDQ Insights API - Getting Started - Exploring the Catalogue

## 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:

| Category | What it covers |
|  --- | --- |
| `mirror` | Volume of business partner records in your Data Mirror |
| `data_quality` | Validation results, defect rates, and rule violations |
| `data_sharing` | Disclosure and sharing status of business partners |
| `bank_accounts` | Bank account records, deduplication, and payments |
| `aml` | AML case counts, ratios, and escalation metrics |


The catalogue is actively growing. New categories and metrics are added as the CDQ platform evolves. The table above reflects the current state, but always query the catalogue endpoint directly for the authoritative and up-to-date list of available metrics.

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:


```json
{
  "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.


For ratio metrics, if the denominator is zero (for example, no closed AML cases to compare against), the API returns `null` rather than zero. This is intentional: a `null` value means the ratio cannot be calculated, which is different from a ratio of zero.

## 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:

| Business question | Metric |
|  --- | --- |
| How many business partners are in our Data Mirror? | `business_partners_count` |
| What share of our records have no critical data quality issues? | `data_quality_ratio` |
| How many AML cases are currently open? | `open_aml_case_count` |
| Are we resolving AML cases as fast as new ones are created? | `open_vs_closed_aml_case_ratio` |
| What proportion of our business partners are disclosed for sharing? | `business_partners_disclosure_rate` |
| How many bank account records do we hold? | `bank_accounts_count` |


## 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!