Overrides API

Create and manage manual overrides to correct automatic matching decisions.

Overview

Overrides allow operators to manually correct the identity graph when automatic matching produces incorrect results. Each override has a type, an optional canonical entity reference, free-form override data, and a reason.

Method	Endpoint	Use Case
List	GET /v1/overrides	List all overrides for your tenant
Create	POST /v1/overrides	Create a new manual override
Delete	DELETE /v1/overrides/:id	Remove an override

---

GET /v1/overrides

List all overrides for the current tenant.

Request

Python

import httpx

resp = httpx.get("https://api.kanoniv.com/v1/overrides",
    headers={"X-API-Key": "kn_..."})
overrides = resp.json()

for ovr in overrides:
    print(f"[{ovr['override_type']}] {ovr['id']}: {ovr['reason']}")

curl

curl "https://api.kanoniv.com/v1/overrides" \
  -H "X-API-Key: kn_..."

Response

Returns an array of ManualOverride objects:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "t_abc123",
    "canonical_entity_id": "660e8400-e29b-41d4-a716-446655440001",
    "override_type": "force_merge",
    "override_data": {
      "entity_a_id": "660e8400-e29b-41d4-a716-446655440001",
      "entity_b_id": "770e8400-e29b-41d4-a716-446655440002"
    },
    "reason": "Same customer, different email domains",
    "created_by": "880e8400-e29b-41d4-a716-446655440003",
    "created_at": "2026-02-05T10:00:00Z",
    "superseded_at": null
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "tenant_id": "t_abc123",
    "canonical_entity_id": "660e8400-e29b-41d4-a716-446655440001",
    "override_type": "force_split",
    "override_data": {
      "external_entity_id": "990e8400-e29b-41d4-a716-446655440005"
    },
    "reason": "Different person, same name",
    "created_by": "880e8400-e29b-41d4-a716-446655440003",
    "created_at": "2026-02-04T15:00:00Z",
    "superseded_at": null
  }
]

Response Fields

Field	Type	Description
id	UUID	Override ID
tenant_id	UUID	Tenant this override belongs to
canonical_entity_id	UUID	Associated canonical entity (null if not applicable)
override_type	string	Override type (e.g., "force_merge", "force_split")
override_data	object	Free-form JSON with override details
reason	string	Human-readable justification (max 500 characters, null if not provided)
created_by	UUID	User ID who created the override (null if created by system)
created_at	timestamp	When the override was created
superseded_at	timestamp	When the override was revoked (null if still active)

---

POST /v1/overrides

Create a new manual override.

Request Body

The request body is a ManualOverride object. The id, tenant_id, and created_by fields are set automatically by the server.

Field	Type	Required	Description
canonical_entity_id	UUID	No	Associated canonical entity ID
override_type	string	Yes	Override type (1--50 characters)
override_data	object	Yes	Free-form JSON with override details
reason	string	No	Human-readable justification (max 500 characters)

Request

Python

import httpx

# Force merge two entities
resp = httpx.post("https://api.kanoniv.com/v1/overrides",
    headers={"X-API-Key": "kn_...", "Content-Type": "application/json"},
    json={
        "canonical_entity_id": "660e8400-e29b-41d4-a716-446655440001",
        "override_type": "force_merge",
        "override_data": {
            "entity_a_id": "660e8400-e29b-41d4-a716-446655440001",
            "entity_b_id": "770e8400-e29b-41d4-a716-446655440002"
        },
        "reason": "Same customer, different email domains (personal vs. work)"
    })
override = resp.json()
print(f"Override created: {override['id']}")

curl

# Force merge
curl -X POST "https://api.kanoniv.com/v1/overrides" \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "canonical_entity_id": "660e8400-e29b-41d4-a716-446655440001",
    "override_type": "force_merge",
    "override_data": {
      "entity_a_id": "660e8400-e29b-41d4-a716-446655440001",
      "entity_b_id": "770e8400-e29b-41d4-a716-446655440002"
    },
    "reason": "Same customer, different email domains (personal vs. work)"
  }'

# Force split
curl -X POST "https://api.kanoniv.com/v1/overrides" \
  -H "X-API-Key: kn_..." \
  -H "Content-Type: application/json" \
  -d '{
    "canonical_entity_id": "660e8400-e29b-41d4-a716-446655440001",
    "override_type": "force_split",
    "override_data": {
      "external_entity_id": "990e8400-e29b-41d4-a716-446655440005"
    },
    "reason": "Different person, same name -- father and son"
  }'

Response

Returns 200 OK with the created ManualOverride (same schema as list response).

---

DELETE /v1/overrides/:id

Remove an override.

Path Parameters

Parameter	Type	Required	Description
id	UUID	Yes	Override ID

Request

Python

import httpx

resp = httpx.delete(
    "https://api.kanoniv.com/v1/overrides/550e8400-e29b-41d4-a716-446655440000",
    headers={"X-API-Key": "kn_..."})
print(f"Deleted: {resp.status_code}")  # 204

curl

curl -X DELETE "https://api.kanoniv.com/v1/overrides/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: kn_..."

Response

Returns 204 No Content on success.