v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Ingestion

Propose a config-only field-map/dialect mapping for a source sample

Inspects a representative sample of a source file and returns a CONFIG-ONLY mapping/dialect proposal (column→canonical-key suggestions, dialect, per-field confidence and rationale). It is ADVISORY and side-effect-free: producing a proposal PERSISTS NOTHING. The operator reviews the proposal and confirms it through the EXISTING field-map declaration path. The tenant is resolved from the JWT and the context/source from the path — never from the body. The response never carries parsed values, amounts, or transactions.

post/v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal

Path parameters

contextIdstring uuid required

Context ID

sourceIdstring uuid required

Source ID

Request body

format'csv' | 'json' | 'xml' | 'camt053'

Declared file format hint

hintsobject

Optional non-secret operator nudges (e.g. locale=pt-BR, has_header=true)

samplestring required

Representative source-file sample

Example request

{
  "format": "csv",
  "sample": "id;value;ccy;posted_at\nA1;10,50;BRL;2025-06-01\n"
}

Response

mappingobject

Proposed canonical field map (canonical key -> source column); null when the advisor could not propose a mapping

Example response

{
  "dialect": {
    "dateStyle": "iso",
    "decimalStyle": "comma",
    "delimiter": "semicolon",
    "encoding": "utf-8"
  },
  "fields": [
    {
      "canonicalKey": "amount",
      "confidence": 0.92,
      "rationale": "numeric column with comma decimal",
      "sourceColumn": "value"
    }
  ]
}