Data Quality Intelligence

Find missing values, format errors, contradictions, and semantic inconsistencies in a structured business record.

Endpoint

POST https://kovca.io/api/v1/data/validate

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

Structure is checked in code: required values, types, formats, enums, ranges, lengths, and the rules you send. Interpretation is used only to judge whether values make sense together. An interpreted finding produces warnings or requires_review, never invalid. Kovca doesn't check values against external sources and never invents a corrected value.

Request body

Field	Type	Description
record_type	string, required	What the record is, for example customer_account. Used as context.
record	object, required	Any JSON object. Nested values are addressed by path, such as address.city or contacts[0].email.
fields	object[], optional	Up to 100 definitions: path, type (string, number, integer, boolean, date, email, url, enum), required, enum_values, min, max, max_length.
rules	object[], optional	Up to 30 rules: { type, field, other } where type is "date_before" \| "equals" \| "required_with".
expected_relationships	string[], optional	Up to 15 relationships in plain language, such as "An employee can't be their own manager".
context	string, optional	Reference context, up to 2,000 characters, such as naming conventions.

Example request

{
  "record_type": "customer_account",
  "record": {
    "company_name": "Northwind Traders",
    "status": "active",
    "billing_email": "billing@northwind.example",
    "contract_start": "2026-03-01",
    "contract_end": "2027-02-28",
    "address": {
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  },
  "fields": [
    {
      "path": "company_name",
      "type": "string",
      "required": true
    },
    {
      "path": "status",
      "type": "enum",
      "enum_values": [
        "Active",
        "Suspended",
        "Closed"
      ],
      "required": true
    },
    {
      "path": "billing_email",
      "type": "email",
      "required": true
    },
    {
      "path": "account_owner",
      "type": "string",
      "required": true
    }
  ],
  "rules": [
    {
      "type": "date_before",
      "field": "contract_start",
      "other": "contract_end"
    }
  ]
}

Response

200 OK

{
  "request_id": "req_Gm5tQ8wLn2RvK7pX",
  "status": "invalid",
  "requires_review": false,
  "issues": [
    {
      "type": "invalid_format",
      "method": "deterministic",
      "field": "status",
      "explanation": "The value isn't one of the allowed values.",
      "evidence": [
        "record.status",
        "fields[1]"
      ]
    },
    {
      "type": "missing_required_value",
      "method": "deterministic",
      "field": "account_owner",
      "explanation": "A required value is missing or empty.",
      "evidence": [
        "record.account_owner",
        "fields[3]"
      ]
    }
  ],
  "missing_information": [
    "account_owner"
  ],
  "suggested_corrections": [
    {
      "field": "status",
      "current": "active",
      "suggested": "Active",
      "reason": "It matches an allowed value except for case or spacing."
    }
  ]
}

Field	Type	Description
request_id	string	Unique ID for this request.
status	"valid" \| "warnings" \| "invalid" \| "requires_review"	invalid (a deterministic failure), requires_review (an uncertain or ambiguous finding), warnings (a confident interpreted finding), or valid.
requires_review	boolean	True when a person should look.
issues	object[]	type, method ("deterministic" \| "model_assisted"), optional field path, a fixed explanation, and evidence.
missing_information	string[]	Paths of required values that are missing.
suggested_corrections	object[]	{ field, current, suggested, reason }. Only when the intended value is certain: a matching enum value except for case, a numeric string, or an email with stray spaces.

Issue types

missing_required_value: A field marked required is missing or empty, or a required_with rule isn't met. Deterministic.
invalid_format: A value doesn't match its declared type, format, enum, range, or length. Deterministic.
relationship_mismatch: A rule (date_before, equals) fails, deterministic; or an expected relationship appears broken or can't be confirmed, model-assisted.
contradictory_values: A value appears to contradict another field. Model-assisted.
semantic_inconsistency: A value appears not to make sense for its field or record type. Model-assisted.
suspicious_value: A value looks like a placeholder or test value. Model-assisted.
ambiguous_value: A value could refer to more than one thing. Model-assisted; always sent for review.

Expected relationships

Request

{
  "record_type": "employee",
  "record": {
    "name": "Jordan Lee",
    "title": "Software Engineer",
    "department": "Engineering",
    "manager": "Jordan Lee",
    "hire_date": "2024-05-01"
  },
  "expected_relationships": [
    "An employee can't be their own manager"
  ]
}

Code

curl https://kovca.io/api/v1/data/validate \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "record_type": "customer_account",
  "record": {
    "company_name": "Northwind Traders",
    "status": "active",
    "billing_email": "billing@northwind.example",
    "contract_start": "2026-03-01",
    "contract_end": "2027-02-28",
    "address": {
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  },
  "fields": [
    {
      "path": "company_name",
      "type": "string",
      "required": true
    },
    {
      "path": "status",
      "type": "enum",
      "enum_values": [
        "Active",
        "Suspended",
        "Closed"
      ],
      "required": true
    },
    {
      "path": "billing_email",
      "type": "email",
      "required": true
    },
    {
      "path": "account_owner",
      "type": "string",
      "required": true
    }
  ],
  "rules": [
    {
      "type": "date_before",
      "field": "contract_start",
      "other": "contract_end"
    }
  ]
}'

Errors

400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

Up to 30 non-empty text and number values are interpreted per request; booleans and blanks aren't.
No external verification: addresses, tax IDs, and companies aren't looked up.
Not a schema engine: send field definitions for structure, and use your own schema validation for anything beyond them.
Request data is processed to produce the result and is not stored by Kovca.