Formats

GET /v1/formats — the live registry of supported message formats, versions, and conversion pairs, plus how the catalogue is organised into message families. Always trust this endpoint over any static list.

The live registry

GET /v1/formats returns every format this deployment supports, with the conversions each can make:

curl -sS https://api.transmute.403fin.io/v1/formats \
  -H "Authorization: Bearer $TRANSMUTE_KEY"

{
  "formats": [
    {
      "id": "camt.053",
      "name": "Bank to Customer Statement (camt.053)",
      "kind": "mx",
      "versions": ["camt.053.001.02", "camt.053.001.08", "..."],
      "convertsTo": ["accounting-transaction", "bai2", "camt.053", "csv-generic", "...", "mt940", "..."]
    },
    {
      "id": "mt940",
      "name": "Customer Statement Message (MT940)",
      "kind": "mt",
      "versions": [],
      "convertsTo": ["accounting-transaction", "bai2", "camt.052", "camt.053", "camt.054", "csv-generic", "..."]
    }
  ],
  "srVersions": ["SR2025", "SR2026"],
  "validationLevels": ["syntax", "schema", "..."],
  "profiles": [ { "id": "de-multicash", "description": "...", "options": { "...": "..." } } ]
}

Field	Meaning
`formats[].id`	The value you pass as `from`/`to` on convert, normalize and validate
`formats[].kind`	`mt` (SWIFT MT), `mx` (ISO 20022), `file` (bank and accounting files: BAI2, CSV, OFX, spreadsheets, accounting transactions) or `json` (`canonical` input and the `normalized-json` output of normalize)
`formats[].versions`	ISO 20022 message versions accepted as input; pin an output version with `targetVersion`
`formats[].convertsTo`	Valid `to` values from this source, sorted
`srVersions`	Standards Releases accepted as the `srVersion` option
`validationLevels`	Levels `/v1/validate` serves on this deployment
`profiles`	Dialect presets for the `profile` option, see Dialect profiles

Use it, don't hardcode it

The registry grows with Standards Releases and new format support. Query it at startup (or cache it briefly) rather than baking a pair list into your code. Asking for a pair outside the registry gets an unsupported-conversion 422, and an id it doesn't know gets unsupported-format 422.

The endpoint requires the formats:read scope (granted by default) and is never metered.

The catalogue at a glance

Today the registry holds 56 format ids and 193 conversion pairs. The response also includes the normalized-json pseudo-format, which is the output of /v1/normalize and has no convertsTo.

Every conversion goes through a format-neutral model, and the formats are grouped into families by what the message means: a statement, a customer payment, a cancellation request, and so on. The rules:

Pairs exist only inside a family. A statement never converts to a payment. A direct debit never converts to a credit transfer.
MT to MT and MX to MX pairs exist only where listed. The five same-kind pairs are camt.052 to camt.052, camt.052 to camt.053, camt.053 to camt.053, camt.055 to camt.056, and pain.001 to pain.001 (the version bridge). File formats may convert to other file formats (bai2 to csv-xero). No format converts to itself unless it's in that list.
Some formats work in one direction only. canonical, csv-payments and xlsx-payments are sources only. The accounting targets (csv-xero, csv-generic, csv-quickbooks, csv-sage, ofx, qfx, qbo, accounting-transaction) are targets only.
Normalize-only formats can be read by /v1/normalize and /v1/validate but not converted: camt.029, mt199, mt299, and pain.002 as a source. pain.002 can be rendered from canonical JSON.

Family	MT	ISO 20022	Other	Pairs
`statement`	`mt940`, `mt950`, `mt942`, `mt900`, `mt910`	`camt.053`, `camt.052`, `camt.054`	`bai2` both ways; `canonical` in; `csv-xero`, `csv-generic`, `csv-quickbooks`, `csv-sage`, `ofx`, `qfx`, `qbo`, `accounting-transaction` out	137
`payment`	`mt103`	`pacs.008`	`canonical` in; `accounting-transaction` out	7
`fi`	`mt202`, `mt205`	`pacs.009`		4
`initiation`	`mt101`	`pain.001`	`canonical`, `csv-payments`, `xlsx-payments` in	9
`collection`	`mt104`	`pain.008`	`canonical` in	4
`return`	`mt103-retn`, `mt202-retn`	`pacs.004`		4
`reject`	`mt103-rejt`, `mt202-rejt`	`pacs.002`; `pain.002` out	`canonical` in	6
`investigation`	`mt192`, `mt292`	`camt.056`; `camt.055` in		7
`query`	`mt195`, `mt295`	`camt.110`		4
`answer`	`mt196`, `mt296`	`camt.111`		4
`notice`	`mt210`	`camt.057`		2
`charges`	`mt191`, `mt291`	`camt.106`		4
`request`	`mt920`	`camt.060`	`canonical` in	4

Inside a family, MT sources convert to the ISO 20022 targets and back. File and JSON formats join where the table shows them. The exact pairs per source are convertsTo in the live registry. For what each family maps and what it drops, see Message families.

Was this page helpful?