Skip to main content

Get / Update / Delete Config

Get matching configuration details, update field mappings and weights, or delete a configuration. Deleting a config does not remove past run results.

Retrieve, update, or delete a matching configuration. Updates to field mappings and thresholds take effect on the next run — they do not retroactively change past results. Deleting a config removes the configuration but preserves all historical run results for audit purposes.

Use GET to inspect the current field mappings, threshold, and targeting mode before running a match. Use PUT to adjust weights, swap strategies, or change the threshold — a common pattern is to lower the threshold after reviewing low-confidence results, then re-run to capture more matches.

The PUT response returns the full updated config. The reference_data_id cannot be changed after creation — to match against a different dataset, create a new config. The links.runs URL provides a convenient shortcut to trigger a new run with the updated config.

Deleting a config is safe for audit — all historical run results, including per-document evidence and confidence scores, are preserved. Pair config updates with the generate strategy endpoint to get AI-recommended adjustments based on your reference dataset.

Past run results are immutable. Updating field mappings or thresholds only affects future runs — re-run matching after config changes to see the updated results.
GET/v1/matching/configs/:id

Response (GET)

Response fields

idstringConfiguration UUID.
namestringConfig name.
reference_data_idstringReference dataset ID.
target_typestringTargeting mode.
target_valueobjectTarget-specific values.
field_mappingsarrayField mapping array.
thresholdnumberConfidence threshold.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
links.selfstringURL to this config.
links.runsstringURL to trigger a run.

Response (GET)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Vendor Invoice Match",
  "reference_data_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "target_type": "run",
  "target_value": {},
  "field_mappings": [
    { "source": "vendor_name", "target": "name", "strategy": "fuzzy", "weight": 0.4 },
    { "source": "invoice_date", "target": "date", "strategy": "date_range", "weight": 0.3 },
    { "source": "amount", "target": "total", "strategy": "numeric_range", "weight": 0.3 }
  ],
  "threshold": 0.85,
  "created_at": "2024-10-01T08:00:00.000Z",
  "updated_at": "2024-10-01T08:00:00.000Z",
  "links": {
    "self": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "runs": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run"
  }
}
PUT/v1/matching/configs/:id

Response (PUT)

Response fields

idstringConfiguration UUID.
namestringUpdated config name.
reference_data_idstringReference dataset ID (unchanged).
field_mappingsarrayUpdated field mapping array.
thresholdnumberUpdated confidence threshold.
updated_atstringISO 8601 last update timestamp.
links.selfstringURL to this config.
links.runsstringURL to trigger a run.

Response (PUT)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Vendor Invoice Match v2",
  "reference_data_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "target_type": "run",
  "target_value": {},
  "field_mappings": [
    { "source": "vendor_name", "target": "name", "strategy": "fuzzy", "weight": 0.5 },
    { "source": "invoice_date", "target": "date", "strategy": "date_range", "weight": 0.3 },
    { "source": "amount", "target": "total", "strategy": "numeric_range", "weight": 0.2 }
  ],
  "threshold": 0.80,
  "created_at": "2024-10-01T08:00:00.000Z",
  "updated_at": "2024-10-05T14:30:00.000Z",
  "links": {
    "self": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "runs": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run"
  }
}
DELETE/v1/matching/configs/:id

Response (DELETE)

Response fields

deletedbooleanAlways true on success.

Response (DELETE)

{ "deleted": true }

Errors

Error responses

401unauthorizedMissing or invalid API key.
404not_foundNo matching config with this ID exists for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List Configs
Run Matching