Transmutify Docs
POSThttps://api.transmutify.io/v1/transformations/file

Initialize a file-based transformation run

Creates a run in `awaiting_upload` status and returns temporary upload instructions for the caller's source file. The processing starts immediately after upload completed. Use the returned `id` to inspect status while the hosted Review UI handles review and approval.

Requires a bearer token. Learn more about authentication

Request body

Send as application/json

schema_idstring required

Target schema UUID that defines the desired output fields for this transformation.

provider_idstring | null

AI provider UUID used for AI-assisted structured mapping or image extraction. Required when filename is JPG, PNG, or WebP; omit for manual structured-file mapping.

dry_runboolean

When true, the run generates synthetic output and skips review preparation quota consumption.

filenamestring required

Original source filename used to create upload instructions. CSV, TSV, TXT, and XLSX start structured-file mapping; JPG, PNG, and WebP start image extraction after upload completion.

Max length: 255 characters

input_has_headerboolean | null

Optional override for whether the uploaded structured file contains a header row. Ignored for image filenames.

output_formatstring

Output artifact format produced after hosted review approval. Defaults to JSON when omitted.

jsoncsv

notify_urlstring | null

Optional webhook URL for transformation completion notifications. Production callbacks must use HTTPS.

success_callbackstring | null

Optional hosted-review success callback used after a reviewer approves the review. Production callback URLs must use HTTPS.

cancel_callbackstring | null

Optional hosted-review cancel callback used after a reviewer cancels the review. Production callback URLs must use HTTPS.

localestring | null

Optional locale for the hosted review UI translations. Case-insensitive; unsupported values fall back to `en`.

endefrnlesitplar

appearancestring | null

Optional hosted-review appearance persisted for all review interactions.

lightdark

metadataobject | null

Optional caller-defined metadata JSON object echoed in transformation responses and customer webhooks.

column_labelsobject | null

Optional JSON object keyed by schema field name. Values override the labels shown in the hosted Review UI.

Responses

idstring required

Stable UUID of the transformation run. Use this in subsequent requests against the run.

statusstring required

Current lifecycle status. File runs start as `awaiting_upload`; raw runs start as `queued`.

stagestring required

Current stage of the run. Create responses start in `review`.

input_sourcestring required

Input source for this run (`upload`, `raw`, or `image`).

schema_idstring required

UUID of the schema this run targets.

review_urlstring required

Signed hosted-review URL for end-user review.

uploadobject required

Pre-signed upload instructions for the source file.

urlstring required
headersobject required
methodstring required
expires_atstring required
cURL
curl -X POST 'https://api.transmutify.io/v1/transformations/file' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schema_id": "9b2e1f6c-8e6d-4a3b-9c1f-7d2e5a8b3c4d",
    "provider_id": "9b2e1f6c-8e6d-4a3b-9c1f-7d2e5a8b3c4d",
    "dry_run": false,
    "filename": "string",
    "input_has_header": false,
    "output_format": "json",
    "notify_url": "https://example.com/webhooks/transmutify",
    "success_callback": "https://example.com/webhooks/transmutify",
    "cancel_callback": "https://example.com/webhooks/transmutify",
    "locale": "en",
    "appearance": "light",
    "metadata": {
      "external_id": "import-2026-01-15",
      "source": {
        "system": "hris",
        "batch": 42
      }
    },
    "column_labels": {
      "employee_id": "Employee ID",
      "work_email": "Work email",
      "department": "Department"
    }
  }'
Response · 201
{
  "id": "019dc45d-3b81-7369-a776-2d95c5caab97",
  "status": "awaiting_upload",
  "stage": "review",
  "input_source": "upload",
  "schema_id": "019dc458-710e-73a0-9b5a-bb7d6f7ddc42",
  "review_url": "https://review.transmutify.io/reviews/019dc45d-3b81-7369-a776-2d95c5caab97?signature=...",
  "upload": {
    "url": "https://storage.example.com/transmutify/uploads/019dc45d-3b81-7369-a776-2d95c5caab97/input.csv",
    "headers": {
      "Content-Type": "text/csv"
    },
    "method": "PUT",
    "expires_at": "2026-01-15T12:45:00Z"
  }
}