Skip to main content

Create Config

Create a matching configuration with field mappings, comparison strategies (exact, fuzzy, date_range, numeric_range), and per-field weights that sum to 1.0.

Create a matching configuration that defines how documents are compared against a reference dataset. Each field mapping specifies a source field (from extracted documents), a target column (in the reference data), a comparison strategy, and a relative weight.

The typical workflow is: upload reference data via POST /v1/matching/reference-data, create a config with field mappings, then trigger a run via POST /v1/matching/configs/:id/run. For complex datasets, use POST /v1/matching/strategies/generate first to get AI-recommended mappings and weights.

The response returns the config with the saved field_mappings, threshold (defaults to 0.85), and links.runs URL for triggering runs. The reference_data_id is fixed at creation — to match against a different dataset, create a new config.

Choose strategies carefully: use exact for standardized codes and IDs, fuzzy for names with potential typos, date_range for dates with tolerance, and numeric_range for amounts with rounding differences. Weights must sum to 1.0 — fields with higher weights have more influence on the overall confidence score.

Field weights should sum to 1.0. The overall confidence score for a match is the weighted sum of per-field scores. Use the generate strategy endpoint to get AI-recommended mappings if you are unsure which fields and weights to use.
POST/v1/matching/configs

Response

Response fields (201 Created)

idstringConfiguration UUID.
namestringConfig name.
reference_data_idstringReference dataset ID.
target_typestringTargeting mode.
target_valueobjectTarget-specific values.
field_mappingsarraySaved field 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 (201 Created)

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

Errors

Error responses

400validation_errorMissing required fields (name, reference_data_id, field_mappings), or invalid field mapping format.
401unauthorizedMissing or invalid API key.
404not_foundThe specified reference_data_id does not exist for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List Configs
Generate Strategy