Set up DQ Rules and Monitors via API

This guide shows you how to set up DQ rules and monitoring programmatically, without manual work in the web application. It covers two common scenarios: onboarding a newly connected data source, and importing rule definitions from an external source such as Microsoft Excel or Collibra.

Prerequisites

Before using the Data Quality API:

Configure authentication as described in API Authentication.
Get familiar with the Data Quality API: see the Data quality rules and the Data quality monitors in the API reference.

Onboard a new data source

When a new data source is connected and its catalog items are available, set up data quality end to end: create the DQ rules, create and configure a DQ monitor, run the first evaluation, and review the results. You can also create DQ dashboards.

To create rules one at a time, as drafts you review and then publish, follow Step 1: Create DQ rules and Step 2: Publish the rules.

To create multiple rules at once, use Create rules in batch instead. Batch-created rules must be complete (that is, they must already meet the publish requirements listed in Publish rule), and they are published directly. Then continue with Step 3: Create a DQ monitor.

Step 1: Create DQ rules

Create the DQ rules you want to apply to the data. Rules are created as drafts. You can assign a draft rule to a monitor, but you can publish the monitor only after every rule it applies is published.

Request: Create a DQ rule

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email format validation",
    "inputGroups": {
      "new_input-group": {
        "name": "Input",
        "inputs": {
          "new_email": { "name": "email", "dataType": "STRING" }
        }
      }
    },
    "implementation": { ... }
  }'

Response: Created rule draft (trimmed)

{
  "urn": "urn:ata:{your-tenant}:data-quality:rule:{ruleId}",
  "draftType": "NEW",
  "name": "Email format validation",
  "inputGroups": {
    "{inputGroupId}": {
      "urn": "urn:ata:{your-tenant}:data-quality:rule-input-group:{inputGroupId}",
      "correlationId": "new_input-group",
      "name": "Input",
      "inputs": {
        "{inputId}": {
          "urn": "urn:ata:{your-tenant}:data-quality:rule-attribute:{inputId}",
          "correlationId": "new_email",
          "name": "email",
          "dataType": "STRING"
        }
      }
    }
  },
  "implementation": { ... }
}

Save the urn of the rule and the urn of each input. You need them in Step 4 to assign the rule and map its inputs.

For the rule structure and details, see Create rule. For the request body fields and the response fields, see the Data quality rules in the API reference.

Step 2: Publish the rules

Publish each rule so it can be used in monitors.

Request: Publish a DQ rule

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

Publishing requires the rule to be complete (including a name, an implementation with conditions, and at least one input group with joined: false). An incomplete rule fails with a 400 error listing what is missing. For details, see Publish rule.

Step 3: Create a DQ monitor

Create a DQ monitor for the catalog item. The monitor is created as a draft.

Request: Create a DQ monitor

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer data monitor"}'

The response returns the created monitor, including its URN. Save it for the following steps.

For details, see Create DQ monitor. For the request body fields and the response fields, see the Data quality monitors in the API reference.

Step 4: Assign rules and set thresholds

Assign the published rules to the DQ monitor and configure DQ thresholds by updating the monitor draft (see Update DQ monitor).

Rules are assigned as rule instances in manualRuleInstances. Reference the rule by its ruleUrn and map the rule’s input attributes to the catalog item’s attributes.

Rule instances, mappings, and thresholds are stored under their own IDs. For new sub-entities, you choose a temporary key that starts with new_ (see How to identify monitor sub-entities).

Request: Assign a rule and set thresholds

curl -X PATCH "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "manualRuleInstances": {
      "new_email-rule": {
        "ruleUrn": "urn:ata:{your-tenant}:data-quality:rule:...",
        "ruleInstanceName": "Email format valid",
        "enabled": true,
        "mappings": {
          "new_email-mapping": {
            "catalogItemAttributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:...",
            "ruleAttributeUrn": "urn:ata:{your-tenant}:data-quality:rule-attribute:..."
          }
        },
        "dqThresholds": {
          "new_email-threshold": { "value": 80 }
        }
      }
    },
    "overallDqThresholds": {
      "new_overall-threshold": { "value": 80 }
    }
  }'

The ruleAttributeUrn values come from the rule itself: retrieve the rule and read the urn of each input in inputs. See Get rule.

For parameterized rules, also supply the value of each rule parameter in parameterValues: reference the parameter by its ruleParameterUrn (the urn of the parameter in the rule’s parameters) and provide the value.

For the request body fields and the response fields, see the Data quality monitors in the API reference.

Response: Rule instance under its server-assigned ID (trimmed)

{
  "urn": "urn:ata:{your-tenant}:data-quality:dq-monitor:{dqMonitorId}",
  "draftType": "NEW",
  "manualRuleInstances": {
    "{ruleInstanceId}": {
      "ruleInstanceUrn": "urn:ata:{your-tenant}:data-quality:rule-instance:{ruleInstanceId}",
      "correlationId": "new_email-rule",
      "ruleUrn": "urn:ata:{your-tenant}:data-quality:rule:...",
      "ruleInstanceName": "Email format valid",
      "enabled": true,
      "mappings": {
        "{mappingId}": {
          "correlationId": "new_email-mapping",
          "catalogItemAttributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:...",
          "ruleAttributeUrn": "urn:ata:{your-tenant}:data-quality:rule-attribute:..."
        }
      },
      "dqThresholds": {
        "{dqThresholdId}": {
          "urn": "urn:ata:{your-tenant}:data-quality:dq-threshold:{dqThresholdId}",
          "correlationId": "new_email-threshold",
          "value": 80
        }
      }
    }
  },
  "overallDqThresholds": {
    "{overallDqThresholdId}": {
      "urn": "urn:ata:{your-tenant}:data-quality:dq-threshold:{overallDqThresholdId}",
      "correlationId": "new_overall-threshold",
      "value": 80
    }
  }
}

Each new sub-entity is returned under its server-assigned ID (for example, {ruleInstanceId}), with your temporary key in correlationId.

The update changes only the rule instances you send. Everything else stays unchanged. For the full update semantics, see Update DQ monitor.

Step 5: Publish the monitor

Publish the monitor draft to make the configuration live.

Request: Publish the DQ monitor

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

For details, see Publish DQ monitor.

Step 6: Run the first evaluation

Start the DQ monitor processing to run the first evaluation and verify the setup works end to end.

Request: Start the DQ monitor processing

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings" \
  -H "Authorization: Bearer {access_token}"

Response: Links for polling and for the results

{
  "polling": {
    "href": "https://{your-environment}.ataccama.one/api/processing/v1/workflows/urn:ata:{your-tenant}:processing:workflow:..."
  },
  "result": {
    "href": "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/urn:ata:{your-tenant}:processing:workflow:.../results"
  }
}

The processing runs asynchronously. Poll polling.href until the processing completes, then retrieve the results from result.href.

For the request parameters and the response fields, see the Data quality monitor processing in the API reference.

For polling details and how to handle failed runs, see Poll for completion and Handle failed processing runs. If the response contains no result link, see Start the DQ monitor processing.

Step 7: Review the results

After the processing completes, retrieve the results and check that the rules were applied as expected: each assigned rule appears in ruleInstanceResults, and threshold breaches (if any) appear as findings.

Request: Retrieve the latest DQ evaluation results

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/latest/results/dq-evaluation" \
  -H "Authorization: Bearer {access_token}"

For the full response structure, see the Data quality monitor processing in the API reference.

Step 8: Create a DQ dashboard

This step is optional.

Create a DQ dashboard that aggregates the results of the monitor you created in Step 3: Create a DQ monitor, then publish the dashboard. A dashboard can aggregate published monitors only, so complete Step 5: Publish the monitor first. To aggregate more monitors, add their URNs to dqMonitorUrns.

Create the dashboard:

Request: Create a DQ dashboard

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dashboards" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer data dashboard",
    "dqMonitorUrns": [
      "{dqMonitorUrn}"
    ]
  }'

The response returns the created dashboard draft, including its URN. Save it for publishing the dashboard.

Publish the dashboard:

Request: Publish the DQ dashboard

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dashboards/{dqDashboardUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

The API does not return the aggregated quality. To view it, open the dashboard in the web application.

For details, see Create DQ dashboard and Publish DQ dashboard.

Import rules from an external source

To migrate rule definitions maintained outside Ataccama ONE (for example, in Excel or Collibra), import them one at a time with a script that iterates through the source list and calls the rule creation API for each definition.

Imported rules are created as drafts. This gives your team a review checkpoint: complete and validate each rule, then publish it either in the web application or through the API publish endpoint.

If the source definitions are already complete and validated and no review step is needed, use Create rules in batch instead. The batch endpoint imports up to 100 rules per request directly as published versions, skipping the draft review this workflow relies on.

Script example: Import rules from an external source as drafts

import requests

rules = load_rules_from_source()  # for example, parse an Excel export or a Collibra API response

for rule in rules:
    response = requests.post(
        f"{BASE_URL}/data-quality/v1/rules",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "name": rule["name"],
            "description": rule.get("description"),
            "inputGroups": rule["input_groups"],
            "implementation": rule.get("implementation"),  # may be omitted; drafts can be incomplete
        },
    )
    response.raise_for_status()
    print(f"Imported as draft: {rule['name']} -> {response.json()['urn']}")

Drafts can be created incomplete, so each rule imports successfully even when its logic cannot be fully converted from the source definition. A rule only needs to be complete when you publish it. 400 validation errors in the loop therefore indicate malformed requests (for example, an invalid data type) rather than incomplete logic.

After the import:

Review the draft rules in the web application and complete any missing information that could not be imported from the source system. For details on completing the rule definition, see Create DQ Rule in the Rule Library.
Publish each rule, either in the web application or via the API publish endpoint (see Step 2: Publish the rules).

Rule and monitor lifecycle

Rules, monitors, and dashboards follow a draft and publish lifecycle: creation produces a draft, and publishing promotes it to the published version. For how drafts, publishing, and batch creation work for each of them, see the Data quality rules, the Data quality monitors, and the Data quality dashboards in the API reference.

Troubleshooting

400 Bad Request when publishing a rule

The rule is incomplete: it does not yet meet the publish requirements listed in Publish rule. The 400 response lists what is missing.

To check a current draft of the rule, retrieve it with ?version=DRAFT.

404 Not Found when creating a monitor

The catalog item does not exist (RESOURCE_NOT_FOUND). Check that the tenant segment of the URN matches your environment and that the catalog item is published. A malformed URN is rejected with 400 Bad Request (VALIDATION_ERROR) instead; the expected format is urn:ata:{tenant}:catalog:catalog-item:{uuid}.

404 Not Found when creating a dashboard

A URN in dqMonitorUrns does not exist or is not published, or your API client has no access to it (RESOURCE_NOT_FOUND). No dashboard is created.

Check that the monitor was published in Step 5: Publish the monitor and that the URN matches the one returned in Step 3: Create a DQ monitor.

Assigned rule has no effect in the evaluation results

Check that:

The rule is published.
The rule instance is enabled (enabled: true).
The attribute mappings reference existing catalog item attributes.

Next steps

Data quality monitors: Manage DQ monitor configuration in detail.
Data quality dashboards: Create and publish DQ dashboards in detail.
Run DQ Evaluation from Pipelines: Run DQ evaluation from your pipelines.
Data quality monitor processing: Retrieve and interpret DQ results.

Was this page useful?