Entity Resolution Recipe API

The Entity Resolution recipe has no API resource of its own. It is a guided flow over the same objects you can create by hand. Reproducing it programmatically means calling the standard endpoints in the order the recipe does: create the check, dry-run it, activate it, scan, materialize the golden set, and acknowledge the anomaly. The recipe's AI suggestions come from a small set of assist endpoints that you can call too.

All endpoints use the base URL of your Qualytics deployment (e.g., https://your-instance.qualytics.io/api) and require a Personal API Token. Every call needs the Member role. The team permission on the source datastore depends on the step, from Reporter for the AI assists to Editor for the scan and the materialize. See Permissions for the full matrix.

The Recipe Sequence

1. Create the Check as a Draft

The Review step creates the check in Draft status. type takes String, Numeric, or DateTime; role is compare for weighted evidence and block for a hard boundary, and block fields always use exact comparison. weight is any non-negative number, and at least one compare field must have a positive weight. The recipe normalizes its suggested weights to sum to 1, but the API does not require that.

The recipe starts the threshold at 0.75, which is why the example sends it explicitly. A check created by hand without the field uses the platform default of 0.7.

Endpoint: POST /quality-checks

Permission: Drafter team permission on the datastore for a Draft, Author to create it Active directly

curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Entity Resolution check on customers",
    "container_id": 145,
    "rule": "entityResolution",
    "status": "Draft",
    "properties": {
      "distinct_field_name": "customer_id",
      "composite_match_threshold": 0.75,
      "target_fields": [
        {
          "type": "String",
          "field_name": "company_name",
          "role": "compare",
          "comparison_type": "fuzzy",
          "pair_substrings": true,
          "pair_homophones": true,
          "consider_term_frequency": false,
          "weight": 0.5
        },
        {
          "type": "String",
          "field_name": "billing_email",
          "role": "compare",
          "comparison_type": "fuzzy",
          "weight": 0.3
        },
        {
          "type": "String",
          "field_name": "country",
          "role": "compare",
          "comparison_type": "exact",
          "weight": 0.2
        }
      ]
    }
  }'

Before creating, the Review step also asks whether an active Entity Resolution check already exists for the asset. The same probe is available as POST /quality-checks/find-conflicting. It takes {"quality_check": <the create payload>}, optionally with exclude_check_id to ignore a check you are editing, needs the Drafter team permission, and responds with conflicting_check set to the overlapping check or to null.

2. Dry-Run the Check

The Validate step runs the check on a sample of up to 10,000 records per partition.

Endpoint: POST /quality-checks/{id}/dry-run

Permission: Drafter team permission on the datastore

curl -X POST "https://your-instance.qualytics.io/api/quality-checks/812/dry-run" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "max_records_analyzed_per_partition": 10000 }'

3. Activate the Check

Validate finishes by setting the check to Active. The bulk update endpoint takes a list, so several checks can be activated at once.

Endpoint: PATCH /quality-checks

Permission: Author team permission on the datastore

curl -X PATCH "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{ "id": 812, "status": "Active" }]'

PATCH /quality-checks/activate with [{ "id": 812 }] is a more forgiving alternative: it activates every check it can and reports the ones it could not, with the reason for each, instead of failing the whole request.

4. Run the Full Scan

The Scan step runs a full scan of every record in the selected table, not only the records changed since the last scan.

Endpoint: POST /operations/run

Permission: Editor team permission on the datastore

curl -X POST "https://your-instance.qualytics.io/api/operations/run" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "scan",
    "datastore_id": 12,
    "container_names": ["customers"],
    "incremental": false
  }'

The recipe also raises enrichment_source_record_limit so that up to 100,000 source records of the duplicates are stored for remediation, and sets archive_duplicate_anomalies to false so the new anomaly does not archive the previous run's. Once the scan completes, list the check's anomalies with GET /anomalies?quality_check={check_id} and read the duplicates with GET /anomalies/{id}/source-record. Each source record carries the entity it was grouped into in the _qualytics_entity_id column.

5. Materialize the Golden Set

The Materialize step writes the records you kept to the enrichment destination. The records to leave out travel as the list of their distinction-field values in exclusion_values, and materialize_inverse asks for the companion output of excluded records.

Endpoint: POST /operations/run

Permission: Editor team permission on the datastore

curl -X POST "https://your-instance.qualytics.io/api/operations/run" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "materialize",
    "datastore_id": 12,
    "container_names": ["customers"],
    "exclusion_field": "customer_id",
    "exclusion_values": ["CUST-2417", "CUST-3090", "CUST-5561"],
    "materialize_inverse": true
  }'

Requests that break the exclusion rules are rejected with 422 Unprocessable Entity. The message arrives inside the standard validation error list, prefixed with Value error,, and reads one of:

• exclusion_filter and exclusion_field/exclusion_values are mutually exclusive
• exclusion_field is required when exclusion_values is set
• exclusion_values is required when exclusion_field is set
• exclusion_values exceeds the maximum of 25000 values
• exclusion_values exceeds the maximum total length of 1000000 characters
• exclusion_filter exceeds the maximum length of 4000 characters
• exclusion_filter may not call the '<name>' function; only comparison and logical predicates are permitted

A materialize on a datastore without a linked enrichment destination, or with a disconnected one, is rejected with 409 Conflict.

6. Acknowledge the Anomaly

After the golden set is written, the recipe acknowledges the anomaly whose duplicates it remediated.

Endpoint: PUT /anomalies/{id}

Permission: Author team permission on the datastore

curl -X PUT "https://your-instance.qualytics.io/api/anomalies/4021" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Acknowledged" }'

AI Assist Endpoints

The recipe's AgentQ suggestions come from six endpoints under /recipes/entity-resolution/. Each call stands alone: it takes the identifiers of the objects involved, asks the configured AI provider, and returns the suggestion with its reasoning. They all need the Member role, the Reporter team permission or above on the datastore of the container, check, or operation named in the request, and an AI integration configured for AgentQ. The AgentQ data sharing level must allow the step: Metadata Shared for all of them except golden-record recommendations, which need Source Data Shared.

curl -X POST "https://your-instance.qualytics.io/api/recipes/entity-resolution/recommend-golden-records" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "container_id": 145,
    "quality_check_id": 812,
    "entity_clusters": [
      {
        "entity_id": 7,
        "records": [
          { "customer_id": "CUST-0182", "company_name": "Acme Corp", "billing_email": "billing@acme.com", "country": "BR" },
          { "customer_id": "CUST-2417", "company_name": "Acme Corp Ltda", "billing_email": "billing@acmecorp.com", "country": "BR" }
        ]
      }
    ]
  }'

{
  "recommendations": [
    { "entity_id": 7, "preferred_record_index": 0, "reasoning": "Both records describe the same company; the first has the canonical name and the primary billing address." }
  ]
}

The records in one request may total at most 50 across all clusters. Larger sets are sent in several requests, which is how the recipe scores entities a few at a time. Entities the model could not score within the time allowed are left out of the response rather than failing the request, so a partial response is normal. Only when no entity could be scored does the request fail with 503. This endpoint sends the record values themselves to the AI provider; with no AI integration configured it fails and nothing leaves Qualytics.

Error Responses

{ "detail": "Golden-record recommendations needs Source Data Shared, and your Qualytics Administrator has not enabled it." }

{ "detail": "No profiled fields found on this container. Run a profile first." }

{ "detail": "Too many records for one request (120); send fewer clusters so their records sum to at most 50." }

Related

• Entity Resolution API: the full payload and field notes for the check itself.
• Permissions: the roles and team permissions behind each step.
• How It Works: what the run produces and how the outputs are named.
• AgentQ Access Controls: the data sharing levels that gate the assist endpoints.