Samples

GET /v1/samples generates synthetic messages for any format transmute writes. The same parameters always return the same bytes, so samples make stable integration-test fixtures.

What it is for

Integration tests need messages, and real messages contain real people's data. GET /v1/samples builds a synthetic message for a format you name. Every sample uses test-range BICs, published example IBANs and fixed dates, never real data.

Samples are deterministic: the same format, seed, variation and Standards Release always return byte-identical output. Fetch them in CI or check them into your test suite as fixtures; either way you test against the same message every time. Each sample also reads back cleanly and passes schema validation, so a failure in your test points at your code, not at the fixture.

Get a sample

curl -sS "https://api.transmute.403fin.io/v1/samples?format=mt940&seed=2" \
  -H "Authorization: Bearer $TRANSMUTE_KEY" \
  -H "Accept: text/plain"

:20:TGSTMT1
:25:DE89370400440532013000
:28C:1/1
:60F:C260330EUR10000,00
:61:2603310330C1234,56NTRFNONREF
:62F:C260331EUR11234,56

Parameters

Parameter	Required	Meaning
`format`	yes	A format id from `GET /v1/formats`, such as `mt940`, `pacs.008` or `canonical`
`seed`	no	Any 64-bit integer, default `1`. Different seeds give different values (references, amounts, parties) in the same structure
`variation`	no	`0` to `999`, default `0`. Different variations exercise different shapes of the message: which optional fields are present, how many entries, party and agent shapes, text lengths, and so on
`srVersion`	no	The Standards Release to generate for. Also accepted as the `X-Transmute-SR-Version` header; the query parameter wins

Not every variation can be expressed in every format. When the one you asked for cannot, transmute uses the next one that can, and reports the variation it actually used in meta.variation.

canonical samples (the format-neutral JSON that Normalize returns) rotate through payment, statement and initiation documents as variation increases.

Response

`Accept`	You get
`application/json` (default)	The envelope below
`application/xml`	The bare document, for ISO 20022 formats
`text/plain`	The bare message, for MT formats

Asking for XML from an MT format, or plain text from an ISO 20022 format, is an invalid-input 400.

{
  "result": "<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">...",
  "meta": {
    "format": "pacs.008",
    "targetType": "pacs.008.001.08",
    "family": "payment",
    "seed": 42,
    "variation": 0,
    "srVersion": "SR2025"
  }
}

`meta` field	Meaning
`format`	The format you asked for
`targetType`	The exact message version generated
`family`	The message family, such as `payment` or `statement`
`seed`, `variation`	The seed used and the variation actually rendered
`srVersion`	The Standards Release used
`pages`	Present when an MT sample spans several messages; `result` is then an array of strings

Use samples in tests

A few patterns that work well:

Fixture per format. Fetch one sample per format your system handles, with a fixed seed, and store them as test inputs.
Shape coverage. Loop variation from 0 upwards to run your parser against many shapes of the same message.
Round trip. Feed a sample into Convert with verify turned on (see Round-trip verification) to test your whole pipeline without real data.
Standards Release upgrades. Generate the same format, seed and variation with two srVersion values and compare them with Diff.

Errors

Status	When
400 `invalid-input`	`format` is missing, `seed` or `variation` is out of range, an unsupported `srVersion`, or an `Accept` that does not fit the format
422 `unsupported-format`	The format is unknown, or transmute reads it but does not write it (the normalize-only `camt.029`, `mt199` and `mt299`, and the source-only `camt.055`), so there is nothing to generate

Access and billing

Requires the formats:read scope, the same as GET /v1/formats. Samples are never metered and do not count toward your quota. They are rate-limited like the rest of the API.

Was this page helpful?