Skip to content

Validation API

The Validation API provides endpoints for running data quality validation rules against workbooks and raw data, with domain-specific rulesets for CLO and servicer data.

Overview

CalcBridge validation supports:

  • Workbook Validation: Run rules against uploaded workbook data
  • Direct Data Validation: Validate data without uploading a workbook
  • Domain-Specific Rules: CLO and servicer validation rulesets
  • Configurable Thresholds: Customize severity thresholds per validation run
  • Ingest Gate: Block ingestion when critical validation failures are detected

Endpoints

Validate Workbook Data

Run specification-based validation on a workbook's data.

POST /api/v1/validation/workbook/{workbook_id}

Path Parameters

Parameter Type Description
workbook_id string (UUID) Workbook to validate

Query Parameters

Parameter Type Description
domain string Required. Domain: clo or servicer
sheet_name string Optional. Specific sheet to validate
min_severity string Optional. Minimum severity to report

Example Request

curl -X POST "https://api.calcbridge.io/api/v1/validation/workbook/550e8400-e29b-41d4-a716-446655440000?domain=clo" \
  -H "Authorization: Bearer $TOKEN"

response = requests.post(
    f"https://api.calcbridge.io/api/v1/validation/workbook/{workbook_id}",
    headers={"Authorization": f"Bearer {token}"},
    params={"domain": "clo"}
)
report = response.json()
print(f"Passed: {report['passed']} - Issues: {report['summary']['total']}")

Response

{
  "report_id": "val_abc123",
  "passed": false,
  "summary": {
    "critical": 0,
    "errors": 2,
    "warnings": 5,
    "total": 7
  },
  "findings": [
    {
      "rule_id": "clo_par_value_positive",
      "name": "Par Value Positive Check",
      "severity": "error",
      "category": "sanity",
      "message": "2 loans have negative par values",
      "affected_rows": [45, 89],
      "field": "par_value"
    }
  ],
  "validators_run": ["sanity", "regulatory"],
  "domain": "clo",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "sheet_name": "Holdings",
  "ingest_gate": {
    "allowed": true,
    "blocking_findings": []
  },
  "ingest_diagnostics": {
    "schema_drift": [],
    "mapping_audit": {},
    "input_checksums": {}
  }
}

Validate Data Directly

Validate data without uploading a workbook.

POST /api/v1/validation/data

Request Body

Field Type Required Description
data object[] Yes Array of row objects to validate
domain string Yes Domain: clo or servicer
thresholds object No Custom severity thresholds

Response

Returns the same ValidationReportResponse format.

List Validation Rules

Get all available validation rules.

GET /api/v1/validation/rules

Query Parameters

Parameter Type Description
domain string Filter by domain: clo, servicer
category string Filter by category: sanity, regulatory

Response

[
  {
    "rule_id": "clo_par_value_positive",
    "name": "Par Value Positive Check",
    "description": "Validates that all par values are positive numbers",
    "domain": "clo",
    "severity": "error",
    "category": "sanity",
    "thresholds": null
  },
  {
    "rule_id": "clo_cusip_format",
    "name": "CUSIP Format Validation",
    "description": "Validates CUSIP identifiers are 9 characters alphanumeric",
    "domain": "clo",
    "severity": "error",
    "category": "sanity",
    "thresholds": null
  }
]

Get Validation Rule

Get details about a specific validation rule.

GET /api/v1/validation/rules/{rule_id}

Get Default Thresholds

Get default validation thresholds for a domain.

GET /api/v1/validation/thresholds/{domain}

Path Parameters

Parameter Type Description
domain string Domain: clo or servicer

Response

{
  "domain": "clo",
  "thresholds": {
    "par_value_min": 0,
    "spread_range_min": 0,
    "spread_range_max": 2000,
    "rating_required": true,
    "cusip_required": true
  }
}

Rule Categories

Category Description
sanity Basic data integrity checks (types, ranges, required fields)
regulatory Compliance-related validation rules