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
`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

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

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.

Was this page helpful?