Skip to main content

Auto-Configure Reconciliation

Derive a runnable reconciliation config by cross-referencing a reference dataset against your target documents or structuring run.

Auto-configure derives a ready-to-run reconciliation config from your data. It cross-references the reference dataset against the documents or structuring run you target, finds which extracted fields line up with which reference columns, and returns a complete config plus the evidence behind every match.

The target_value is polymorphic on target_type. For documents, pass { "document_ids": [...] }. For run, pass { "run_id": "..." }. The server scopes every referenced document and run to your tenant, loads the extracted values, and compares them against the reference rows to detect field matches by value overlap, name similarity, or both.

If a config is already stored on the dataset, auto-configure merges those stored rules on top of its suggestions, so your manual choices win. The response always echoes the stored_config it merged (or null) so you can see exactly what was layered. The result is a config you can pass straight to POST /v1/reconciliation/run or persist with PUT /v1/reconciliation/config/{referenceDataId}.

POST/v1/reconciliation/auto-configure

Response

Response fields

configobjectPre-built reconciliation config ready to run.
config.lookup_fieldsstring[]Extracted fields whose values seed the anchor lookup.
config.reference_key_columnsstring[]Reference columns indexed for anchor lookup.
config.checksarraySuggested validation checks.
field_matchesarrayEvery detected field match, for transparency.
field_matches[].extracted_fieldstringThe extracted field.
field_matches[].reference_columnstringThe reference column it matched.
field_matches[].match_reasonstringvalue_overlap, name_similarity, or both.
field_matches[].overlap_countintegerNumber of overlapping values for value_overlap matches.
field_matches[].name_similaritynumberName similarity score (0–1).
field_matches[].suggested_check_typestringSuggested check type for this match.
column_classificationobjectReference column classification (key, descriptor, numeric).
collapsed_fieldsobjectExtracted fields collapsed from indexed patterns.
stored_configobject | nullThe stored config merged on top, or null.

Request body

{
  "reference_data_id": "rd_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "target_type": "documents",
  "target_value": {
    "document_ids": ["doc_uuid_1", "doc_uuid_2"]
  }
}

Response

{
  "config": {
    "lookup_fields": ["booking_reference"],
    "reference_key_columns": ["booking_ref"],
    "checks": [
      {
        "name": "freight_amount",
        "type": "numeric_tolerance",
        "extracted_fields": ["freight_total"],
        "reference_fields": ["freight_amount"],
        "tolerance": 0.02
      }
    ]
  },
  "field_matches": [
    {
      "extracted_field": "booking_reference",
      "reference_column": "booking_ref",
      "match_reason": "both",
      "overlap_count": 14,
      "name_similarity": 0.91,
      "ref_role": "anchor",
      "suggested_check_type": "lookup"
    },
    {
      "extracted_field": "freight_total",
      "reference_column": "freight_amount",
      "match_reason": "value_overlap",
      "overlap_count": 9,
      "name_similarity": 0.42,
      "ref_role": "validate",
      "suggested_check_type": "numeric_tolerance"
    }
  ],
  "column_classification": {
    "key_columns": ["booking_ref"],
    "descriptor_columns": ["carrier_name"],
    "numeric_columns": ["freight_amount"]
  },
  "collapsed_fields": {},
  "stored_config": null
}
Treat the returned config as a starting point. Review the field_matches to confirm each suggested check is sensible before you run reconciliation against a large document set.

Errors

Error responses

400bad_requestInvalid body, the dataset is not ready, or no documents with extracted data were found for the target.
401unauthorizedMissing or invalid API key.
404not_foundNo reference dataset with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Run Reconciliation
Analyze Reference Data