Skip to main content

Manage Strategy

Retrieve or update a matching strategy. Strategies define AI-recommended field mappings, blocking keys, thresholds, and edge case handling rules used by smart-run.

Retrieve or update an existing matching strategy. Strategies are created by the generate strategy endpoint and define the field mappings, blocking keys, thresholds, and edge case rules used by smart-run. Use GET to inspect a strategy before applying it, or PATCH to fine-tune individual fields after generation.

The strategy object contains the full configuration used by the matching engine during a smart-run: field mappings with per-field rationale, blocking keys for candidate pre-filtering, hard filters for mandatory constraints, field-level comparison rules, confidence thresholds, and edge case documentation. Each update increments the version counter and updates the version_hash.

Use PATCH to adjust specific strategy fields without regenerating the entire strategy. Common adjustments include tuning thresholds after reviewing initial results, adding blocking keys to improve performance on large datasets, updating field rules to handle edge cases discovered during review, or refining the cardinality and data quality notes for documentation purposes.

The blocking_strategy field controls how blocking keys are applied during candidate pre-filtering: parallel evaluates all blocking keys independently and unions the candidate sets, while ordered_fallback tries keys in order and falls back to the next key only when the current key produces no candidates. Choose parallel for recall-oriented matching and ordered_fallback for precision-oriented matching on large datasets.

Strategy updates are versioned. Each PATCH increments the version number and updates the version_hash. Previous versions are not retained — if you need to preserve a strategy state, save it externally before patching.
GET/v1/matching/strategies/:id

Response (GET)

Response fields

idstringStrategy UUID.
namestring | nullStrategy name.
matching_config_idstring | nullConfig this strategy is associated with.
strategyobjectStrategy object containing field mappings, thresholds, and configuration.
strategy.field_mappingsarrayArray of field mapping objects with source, target, strategy, weight, and rationale.
strategy.thresholdnumberMinimum confidence score for a match.
versionintegerStrategy version number. Incremented on each update.
version_hashstringHash of the strategy content for change detection.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
links.selfstringURL to this strategy.

Response (GET)

{
  "id": "f6a7b8c9-d0e1-2345-fab2-456789012345",
  "name": "Vendor Invoice Strategy v2",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "strategy": {
    "field_mappings": [
      { "source": "vendor_name", "target": "name", "strategy": "fuzzy", "weight": 0.4, "rationale": "High cardinality text — fuzzy handles name variations." },
      { "source": "invoice_date", "target": "date", "strategy": "date_range", "weight": 0.3, "rationale": "Date field — range comparison tolerates minor discrepancies." },
      { "source": "total_amount", "target": "total", "strategy": "numeric_range", "weight": 0.3, "rationale": "Numeric field — range accounts for rounding differences." }
    ],
    "threshold": 0.85
  },
  "version": 2,
  "version_hash": "b2c3d4e5f6a7",
  "created_at": "2024-10-03T10:00:00.000Z",
  "updated_at": "2024-10-04T09:15:00.000Z",
  "links": {
    "self": "/v1/matching/strategies/f6a7b8c9-d0e1-2345-fab2-456789012345"
  }
}
PATCH/v1/matching/strategies/:id

Response (PATCH)

Response fields

idstringStrategy UUID.
namestring | nullStrategy name.
matching_config_idstring | nullConfig this strategy is associated with.
strategyobjectUpdated strategy object.
versionintegerIncremented version number.
version_hashstringUpdated hash of the strategy content.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
links.selfstringURL to this strategy.

Response (PATCH)

{
  "id": "f6a7b8c9-d0e1-2345-fab2-456789012345",
  "name": "Vendor Invoice Strategy v2",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "strategy": {
    "field_mappings": [
      { "source": "vendor_name", "target": "name", "strategy": "fuzzy", "weight": 0.4, "rationale": "High cardinality text — fuzzy handles name variations." },
      { "source": "invoice_date", "target": "date", "strategy": "date_range", "weight": 0.3, "rationale": "Date field — range comparison tolerates minor discrepancies." },
      { "source": "total_amount", "target": "total", "strategy": "numeric_range", "weight": 0.3, "rationale": "Numeric field — range accounts for rounding differences." }
    ],
    "threshold": 0.85
  },
  "version": 3,
  "version_hash": "c3d4e5f6a7b8",
  "created_at": "2024-10-03T10:00:00.000Z",
  "updated_at": "2024-10-05T11:30:00.000Z",
  "links": {
    "self": "/v1/matching/strategies/f6a7b8c9-d0e1-2345-fab2-456789012345"
  }
}

Errors

Error responses

400validation_errorInvalid blocking_strategy value. Must be "parallel" or "ordered_fallback".
401unauthorizedMissing or invalid API key.
404not_foundNo strategy with this ID exists for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Generate Strategy
Run Matching
Create Config