Convert

POST /v1/convert — SWIFT MT ↔ ISO 20022 conversion. Request forms, from/to precedence, options, response envelope, XML/plain output, and paging.

Three ways to send a message

POST /v1/convert accepts exactly three request content types:

`Content-Type`	Body	Typical use
`application/json`	Envelope `{"from", "to", "message", "options"}`	Programmatic clients, SDKs
`text/plain` or `application/x-swift-mt`	Raw MT text	curl, file pipelines — no JSON escaping
`application/xml`	Raw ISO 20022 document	MX sources

Anything else is a invalid-input 400 (never a 415). Bodies are capped at 2 MiB (message-too-large 413); for larger volumes use Batch.

Telling us from and to

For raw (non-envelope) bodies, from/to come from — in precedence order:

The JSON envelope fields (when using application/json)
Query parameters: ?from=mt940&to=camt.053&toVersion=...
Headers: X-Transmute-From, X-Transmute-To, X-Transmute-To-Version

from is optional everywhere — omit it and the engine auto-detects the source format, reported back as meta.detectedType. to is required. The supported pairs are the live registry at GET /v1/formats.

Options

Option	Values	What it does
`translitProfile`	`base` (default), `german`	Transliteration profile for characters outside the SWIFT X charset
`field86Profile`	`plain` (default), `german`	How MT `:86:` remittance info is structured
`strict`	`true`/`false`	Fail instead of warn on lossy steps
`targetVersion`	e.g. `camt.053.001.08`	Pin the target message version (also `?toVersion=` / `X-Transmute-To-Version`). See Message Versions
`dateFormat`	`dmy`, `mdy`, `ymd`	Date rendering in file targets (CSV)
`ofxVersion`	`102`, `220`	OFX target version
`intuBid`	digits	Intuit bank id for QBO/OFX targets
`profile`	`de-multicash`, `at-elba`, `nordic`	A dialect preset: fills the options above that you leave empty (an option you set yourself always wins). The live list and what each fills is `profiles` in `GET /v1/formats`; see Dialect profiles
`srVersion`	`SR2025`, `SR2026`	Standards Release whose mapping rules apply (also the `X-Transmute-SR-Version` header). Unset: the default of your API version. See Standards Releases
`envelope`	`none` (default), `apphdr`, `fin`	Carry the FIN headers or Business Application Header across (also the `X-Transmute-Envelope` header). See Message Envelopes
`trace`	`true`/`false`	Add a `trace` array listing every mapping rule that ran, with paths and names but no values. JSON responses only. See Mapping trace
`verify`	`true`/`false`	Add a `verify` round-trip loss report (`lost`, `warned`, `silent`). JSON responses only. See Round-trip verification
`debulk`	`true`/`false` (default `false`)	Split camt.053/052/054 batch entries into one transaction per `TxDtls`; see Multi-message files
`csvColumns`	list of field ids or `Header=field`	Your own columns for the `csv-generic` target; see BAI2 and accounting CSV
`csvTemplate`	`standard`, `quickbooks-3col`, `quickbooks-4col`, `sage`	Built-in column layout for `csv-generic` / `csv-quickbooks`
`columnMap`	object of header → path	Header mapping for `csv-payments` / `xlsx-payments` input; see Payment spreadsheets
`numberFormat`	`point` (default), `comma`	Amount separators of a `csv-payments` file

In the JSON envelope these ride under options; in raw form they are query parameters of the same names.

Standards Releases. Mapping rules are versioned by the yearly SWIFT Standards Release. Pin srVersion (or an X-Api-Version date) so your output only changes when you choose; Standards Releases explains the SR2026 changes and how the default is chosen.

The response

With the default Accept: application/json:

{
  "result": "<?xml version="1.0" ... camt.053.001.08 ...",
  "warnings": [ { "code": "...", "severity": "...", "...": "..." } ],
  "meta": {
    "detectedType": "mt940",
    "detectedVersion": "",
    "targetType": "camt.053.001.08",
    "durationMs": 4,
    "pages": 1
  }
}

result is a string — or an array of strings when MT paging split the output (MT messages cap at 2,000 characters; a long statement becomes multiple pages, flagged with a PAGED_OUTPUT warning).

Bare-document output

Send Accept: application/xml (MX target) or Accept: text/plain (MT target) to get the converted document itself, no envelope. Warnings can't ride in the body then, so they surface as headers:

X-Transmute-Warnings: 2
X-Transmute-Warnings-Link: https://docs.transmute.403fin.io/warnings
X-Transmute-Pages: 3        # when MT paging occurred (pages concatenated)

Warnings are not stored server-side — to see the full entries, re-issue the request with Accept: application/json.

Read the warnings

Every lossy or assumed step is a structured entry — see the warning registry for all codes and severities. Reconciliation pipelines should treat lossy entries as review items; strict: true turns them into failures instead.

Upload a file, download a zip

You can also send the message as a file upload — one file part, with from, to and options (JSON) as form fields:

curl -sS -X POST https://api.transmute.403fin.io/v1/convert \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -F 'file=@statement.mt940' -F 'to=camt.053'

The upload's file name and content type are ignored; the format is detected from the content. /v1/normalize and /v1/validate take the same form (from, options, and level for validate).

Add Accept: application/zip to get the result as an archive: output-1.<ext> (… output-N when MT paging splits the output) plus warnings.json.

Was this page helpful?