Skip to main content

Manage Strategy

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

Retrieve or update an existing matching strategy. Strategies are created by the generate strategy endpoint and define the field rules, blocking keys, thresholds, and edge case handling 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: per-field comparison rules with rationale, blocking keys for candidate pre-filtering, hard filters for mandatory constraints, confidence bands (auto_commit and auto_reject, with the review band in between), 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

Path parameters

id*stringStrategy UUID.

Response (GET)

Response fields

idstringStrategy UUID.
namestring | nullStrategy name.
matching_config_idstring | nullConfig this strategy is associated with.
strategyobjectStrategy document containing the rules and thresholds used by smart-run.
strategy.field_rulesarrayPer-field comparison rules (extracted_field, reference_field, comparison_type, weight, rationale).
strategy.blocking_keysarrayBlocking key definitions for candidate pre-filtering.
strategy.thresholdsobjectConfidence bands: auto_commit and auto_reject. Scores in between land in the review band.
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": {
    "reasoning_summary": "Match invoices to the vendor master via vendor name with date and amount corroboration.",
    "cardinality": { "expected": "N:1", "rationale": "Many invoices map to one vendor row." },
    "blocking_keys": [
      { "extracted_field": "vendor_name", "reference_field": "name", "transform": "first_n_chars", "transform_param": 4, "rationale": "Cheap candidate pre-filter on the name prefix." }
    ],
    "field_rules": [
      { "extracted_field": "vendor_name", "reference_field": "name", "comparison_type": "fuzzy_string", "weight": 0.4, "rationale": "High cardinality text; fuzzy handles name variations." },
      { "extracted_field": "invoice_date", "reference_field": "date", "comparison_type": "date_range", "weight": 0.3, "tolerance_days": 5, "rationale": "Range comparison tolerates minor discrepancies." },
      { "extracted_field": "total_amount", "reference_field": "total", "comparison_type": "numeric_range", "weight": 0.3, "tolerance_pct": 1, "rationale": "Range accounts for rounding differences." }
    ],
    "thresholds": { "auto_commit": 0.85, "auto_reject": 0.30 },
    "edge_cases": []
  },
  "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

Path parameters

id*stringStrategy UUID.

Body parameters

reasoning_summarystringUpdated human-readable summary of the strategy reasoning.
cardinalityobjectUpdated cardinality assessment: `{ "expected": "1:1 | 1:N | N:1 | N:M", "rationale": "..." }`.
data_quality_notesstring[]Updated notes about data quality considerations.
blocking_keysarrayUpdated blocking key definitions (extracted_field, reference_field, transform) for candidate pre-filtering.
blocking_strategystringBlocking strategy: `parallel` or `ordered_fallback`.
hard_filtersarrayUpdated mandatory constraint filters applied before scoring.
field_rulesarrayUpdated per-field comparison rules and configuration.
thresholdsobjectUpdated confidence bands (`auto_commit`, `auto_reject`).
edge_casesarrayUpdated edge case documentation and handling rules.

Request body

{
  "blocking_keys": [
    { "extracted_field": "vendor_code", "reference_field": "code", "transform": "exact", "rationale": "Stable shared identifier." }
  ],
  "blocking_strategy": "ordered_fallback",
  "thresholds": {
    "auto_commit": 0.90,
    "auto_reject": 0.35
  },
  "data_quality_notes": [
    "Vendor names carry legal-form suffixes (GmbH, Ltd) that need normalization."
  ]
}

Response (PATCH)

The response carries the full merged strategy document with the incremented version. The example below is abbreviated to the patched keys.

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": {
    "blocking_keys": [
      { "extracted_field": "vendor_code", "reference_field": "code", "transform": "exact", "rationale": "Stable shared identifier." }
    ],
    "blocking_strategy": "ordered_fallback",
    "thresholds": { "auto_commit": 0.90, "auto_reject": 0.35 }
  },
  "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