---
title: "Propose a config-only field-map/dialect mapping for a source sample"
method: POST
path: "/v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal"
tags: ["Ingestion"]
---

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

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

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.

## Path parameters

- `contextId` string, uuid, required — Context ID
- `sourceId` string, uuid, required — Source ID

## Request body

- ProposeMappingRequest
  - `format` 'csv' | 'json' | 'xml' | 'camt053' — Declared file format hint
  - `hints` object — Optional non-secret operator nudges (e.g. locale=pt-BR, has_header=true)
  - `sample` string, required — Representative source-file sample

## Response `200`

OK

- MappingProposalResponse
  - `dialect` DialectResponse
    - `dateStyle` string, required — Detected date convention: iso (YYYY-MM-DD), iso_offset (RFC 3339 with offset), dmy (DD/MM/YYYY), or mdy (MM/DD/YYYY)
    - `decimalStyle` string, required — Detected amount decimal convention: dot (1234.56) or comma (1234,56)
    - `delimiter` string, required — Detected CSV field separator: comma, semicolon, tab, or pipe
    - `encoding` string, required — Detected file character encoding: utf-8, utf-8-sig (UTF-8 with BOM), cp1252 (Windows Latin-1), or iso-8859-1
  - `fields` FieldProposalResponse[], nullable, required — Per-field breakdown backing the proposed mapping
    - `canonicalKey` string, required — Canonical field-map key the proposal targets
    - `confidence` number, double, required — Advisor confidence in this mapping, 0.0 (none) to 1.0 (certain)
    - `rationale` string, required — Short human-readable explanation for the suggestion
    - `sourceColumn` string, required — Proposed source column feeding the canonical key
  - `mapping` object — Proposed canonical field map (canonical key -> source column); null when the advisor could not propose a mapping

## Other responses

- `default` — Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)