Entity Resolution Check API

This page documents how to create and manage an Entity Resolution check via the REST API. The check uses the standard Quality Checks endpoints: set rule to entityResolution and configure the distinction field, the target fields, and the composite match threshold under properties. The rule derives its evaluated fields from target_fields, so the fields array is not used. All endpoints share the base URL of your deployment (for example, https://your-instance.qualytics.io/api) and require a Bearer token.

Create

Endpoint: POST /api/quality-checks

Permission: Member role + Author team permission on the container's datastore (Drafter when status is "Draft").

{
    "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
}

Top-Level Field Notes

Target Field Notes

Every entry in target_fields uses the same public structure:

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
}

Numeric Fields

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

Datetime Fields

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

Migrated Checks and the Retired Payload

Checks saved before this structure existed were rewritten automatically, so a GET returns the current shape for every check:

• A target field whose old match_type was exact became a block field with exact comparison, preserving its hard-boundary behavior.
• Every other target field became a compare field, keeping its weight and its type-specific settings.
• The comparison type carries over the old match_type value. Where a stored field had none, it takes the default for its type: "fuzzy" for String, "absolute" for Numeric, and "offset" for DateTime.

The old match_type property is rejected rather than translated. A POST or PUT that still sends it fails with 422 Unprocessable Entity and the message Target fields must use separate 'role' and 'comparison_type' properties, so a script written against the old payload fails loudly instead of saving something different from what it asked for.

Read

Endpoint: GET /api/quality-checks/{id}

Permission: Member role + Reporter team permission on the check's datastore.

curl -X GET "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update

Endpoint: PUT /api/quality-checks/{id}

Permission: Member role + Author team permission on the check's datastore (Drafter when the check stays Draft).

The PUT endpoint requires description; include the check's current description (or a new one) along with the fields you want to change. Send the whole properties object: partial property updates are not merged.

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Similar company records must share a company_id",
    "properties": {
        "distinct_field_name": "company_id",
        "composite_match_threshold": 0.9,
        "target_fields": [
            {"type": "String", "field_name": "company_name", "role": "compare", "comparison_type": "fuzzy", "weight": 4.0}
        ]
    }
  }'

A PUT can update most fields on an existing Entity Resolution check. Three values stay immutable: the rule type, the container the check is attached to, and the associated Check Template. If any of these needs to change, delete the check and create a new one.

Delete

Endpoint: DELETE /api/quality-checks/{id}

Permission: Member role + Author team permission on the check's datastore.

Three query parameters control what happens, mirroring the two-stage flow in the UI:

curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=true&status=Discarded&delete_anomalies=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Error responses

Target Field Validation Messages

A 422 raised by target_fields names the field it rejected, so the response says what to fix without guessing. The same checks run behind the Validate button in the UI, which is why the message you see there matches the one the API returns.

{field} below is the field name in quotes. When an entry carries no field name at all, some of these messages identify it by its place in the array instead, as at position N.