Entity Resolution API

The Entity Resolution check is created and managed through the standard Quality Checks API by setting rule to entityResolution. The check is multi-field: list one entry per evaluated field under properties.target_fields, and choose the distinction field under properties.distinct_field_name. The fields array on the check itself is filled from target_fields and can be sent as an empty list.

Tip

For complete API documentation, including request and response schemas, visit the API docs.

Endpoints

Method	Path	Purpose
`POST`	`/api/quality-checks`	Create a new Entity Resolution check.
`GET`	`/api/quality-checks/{id}`	Retrieve an Entity Resolution check by ID.
`PUT`	`/api/quality-checks/{id}`	Update an existing Entity Resolution check.
`DELETE`	`/api/quality-checks/{id}`	Delete or archive an Entity Resolution check.

Permission: Author (or above) on the target container's team for POST, PUT, and DELETE; Reporter (or above) for GET.

Payload Example

Create a check that compares company name, industry, and country. Industry and country use exact comparison as weighted evidence, but they do not prevent records from being compared:

{
    "description": "Similar company records must share a company_id",
    "rule": "entityResolution",
    "fields": [],
    "container_id": 145,
    "filter": null,
    "properties": {
        "distinct_field_name": "company_id",
        "composite_match_threshold": 0.85,
        "target_fields": [
            {
                "type": "String",
                "field_name": "company_name",
                "role": "compare",
                "comparison_type": "fuzzy",
                "pair_substrings": true,
                "pair_homophones": false,
                "consider_term_frequency": false,
                "weight": 4.0
            },
            {
                "type": "String",
                "field_name": "industry",
                "role": "compare",
                "comparison_type": "exact",
                "weight": 2.0
            },
            {
                "type": "String",
                "field_name": "country",
                "role": "compare",
                "comparison_type": "exact",
                "weight": 1.0
            }
        ]
    },
    "tags": ["master-data"],
    "additional_metadata": {"system": "crm"},
    "anomaly_message_field": null,
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
}

With these weights, an identical name with different industry and country scores 4 / 7, which is below the 0.85 threshold. A slightly different name can still match when industry and country agree.

Top-Level Field Notes

Field	Required	Notes
`description`	Yes	Free-text description shown in the UI.
`rule`	Yes	Must be `"entityResolution"`.
`fields`	Yes	Send `[]`. The list of evaluated fields is computed from `properties.target_fields`.
`container_id`	Yes	ID of the container (table or file) the check runs against.
`filter`	No	SQL `WHERE` expression. Applied before entity resolution runs, so only filtered rows are clustered. Send `null` for no filter.
`properties.distinct_field_name`	Yes	Name of the field that must hold a single value within each resolved entity cluster. Accepted field types: Integral, Fractional, Boolean, String, Date, and Timestamp.
`properties.composite_match_threshold`	Yes	Number between `0.0` and `1.0`. Pairs whose weighted composite score is greater than or equal to this value are treated as matches. Default `0.7`.
`properties.target_fields`	Yes	Non-empty array. Each entry has a data type, a field role, and a compatible comparison type. Comparison fields can also have a weight and type-specific settings.
`tags`	No	List of tag names applied to the check for filtering and organization.
`additional_metadata`	No	Free-form key-value pairs, typically links to governance records or other systems.
`anomaly_message_field`	No	Not applicable to Entity Resolution because the rule emits only Shape Anomalies. Send `null`.
`template_id`	No	ID of a Check Template to associate with the check. Send `null` when not using a template.
`status`	No	`"Active"` (default) or `"Draft"`. Draft checks are not evaluated by Scans.
`owner_id`	No	ID of the user who owns the check. Defaults to the user creating the check.
`default_anomaly_assignee_id`	No	ID of the user automatically assigned to anomalies produced by the check.

Coverage is not supported

Entity Resolution does not accept a coverage value. A cluster is either compliant or non-compliant; there is no fractional tolerance to set.

Target Field Notes

Every entry in target_fields uses the same public structure:

Field	Required	Notes
`type`	Yes	`"String"`, `"Numeric"`, or `"DateTime"`. This must agree with the source field: Numeric accepts Integral or Fractional fields, and DateTime accepts Date or Timestamp fields.
`field_name`	Yes	Name of the source field. A field can appear only once in `target_fields`.
`role`	Yes	`"block"` or `"compare"`. A block field is an exact boundary that must agree before a pair can be compared. A compare field contributes evidence to the composite score.
`comparison_type`	Yes	A comparison supported by the selected `type`. Block fields must use `"exact"`. Compare fields can also use `"exact"` as weighted binary evidence.
`weight`	No	Non-negative number controlling a compare field's contribution to the composite score. Default `1.0`. When comparison fields are configured, at least one must have a positive weight. Weight is ignored for block fields.

For example, this block field creates a hard tenant boundary and does not need a weight:

{
    "type": "Numeric",
    "field_name": "tenant_id",
    "role": "block",
    "comparison_type": "exact"
}

String Fields

{
    "type": "String",
    "field_name": "full_name",
    "role": "compare",
    "comparison_type": "fuzzy",
    "pair_substrings": true,
    "pair_homophones": false,
    "consider_term_frequency": false,
    "weight": 1.0
}

Field	Required	Notes
`comparison_type`	Yes	`"fuzzy"` uses text similarity. `"exact"` scores `1.0` when the values agree and `0.0` when they differ.
`pair_substrings`	No	With fuzzy comparison, a pair where one string contains the other scores `1.0` on this field. Default `false`.
`pair_homophones`	No	With fuzzy comparison, a pair whose values sound alike scores `1.0` on this field. Default `false`.
`consider_term_frequency`	No	With fuzzy comparison, rare tokens carry more weight than common tokens. Default `false`.

Numeric Fields

{
    "type": "Numeric",
    "field_name": "annual_revenue",
    "role": "compare",
    "comparison_type": "relative",
    "offset": 0.05,
    "weight": 1.0
}

Field	Required	Notes
`comparison_type`	Yes	`"exact"` compares equality, `"absolute"` uses a fixed tolerance, and `"relative"` uses a percentage tolerance.
`offset`	No	Non-negative tolerance. With `"absolute"`, the pair scores `1.0` when `\|a - b\| <= offset`. With `"relative"`, use a fraction such as `0.05` for 5%. Default `0.0`.

Datetime Fields

{
    "type": "DateTime",
    "field_name": "registered_at",
    "role": "compare",
    "comparison_type": "offset",
    "offset_seconds": 3600,
    "weight": 1.0
}

Field	Required	Notes
`comparison_type`	Yes	`"exact"` compares equality, `"offset"` allows a difference in seconds, and `"granularity"` compares values in the same time bucket.
`offset_seconds`	No	Non-negative tolerance in seconds for `"offset"`. Default `0`.
`granularity`	No	Bucket used by `"granularity"`: `"Day"`, `"Week"`, `"Month"`, or `"Year"`. Omit it for other comparison types.

Introduction: formal definition, field roles, comparison types, and field scope.
How It Works: blocking, weighted comparison, clustering, and Recipe behavior.
Examples: production scenarios with sample data and resulting anomalies.
FAQ: short answers to common configuration and remediation questions.