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

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

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sample": "id;value;ccy;posted_at\nA1;10,50;BRL;2025-06-01\n",
  "format": "csv",
  "hints": {}
}
'

200

Example

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

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Parámetros de ruta

contextId · string<uuid> · requerido

Context ID

sourceId · string<uuid> · requerido

Source ID

Cuerpo

application/json

sample · string · requerido

Representative source-file sample

Minimum string length: 1

Ejemplo:

"id;value;ccy;posted_at\nA1;10,50;BRL;2025-06-01\n"

format · enum<string>

Declared file format hint

Opciones disponibles: csv, json, xml, camt053

Ejemplo:

"csv"

hints · object

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

Show child attributes

Respuesta

200

application/json

OK

fields · object[] | null · requerido

Per-field breakdown backing the proposed mapping

Show child attributes

dialect · object

Proposed source dialect; null when the advisor has no dialect suggestion

Show child attributes

mapping · object

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

Show child attributes