Transmutify Docs

File upload flow

The full lifecycle of a file-based transformation: initialize, upload, review, approve, and download.

You can walk through this entire flow interactively in the Playground: it executes the same public API calls against your account and the review callback page reconstructs the create and upload cURL examples for your own schemas.

1. Initialize the run

Start with POST /transformations/file. Only schema_id and filename are required — the filename's extension is validated against the supported formats (csv, tsv, txt, xlsx for structured files; jpg, jpeg, png, webp for image extraction).

cURL
curl -X POST 'https://api.transmutify.io/v1/transformations/file' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schema_id": "<schema-id>",
    "provider_id": "<provider-id>",
    "filename": "contacts.xlsx",
    "output_format": "csv",
    "notify_url": "https://example.com/webhooks/transmutify",
    "metadata": {
      "external_id": "crm-import-2026-01-15",
      "source": { "system": "crm", "batch": 42 }
    },
    "column_labels": {
      "work_email": "Work email",
      "department": "Department"
    }
  }'
  • provider_id — optional for structured files. Omit it to skip AI-assisted mapping; the reviewer will map target fields manually in hosted Review. Required for image files because the provider extracts the visible records.
  • notify_url — webhook endpoint for terminal run notifications. Recommended over polling for the final result. See Webhooks.
  • metadata — an arbitrary object echoed back in transformation detail responses and webhook payloads, useful for correlating runs with records on your side and making imports idempotent.
  • column_labels — optional label overrides keyed by schema field name. These become the column names reviewers see in Validate Data.
  • input_has_header — optional override when you already know whether a structured file has a header row.
  • output_format — optional output artifact format after approval. Use json or csv; defaults to json.
Manual structured-file mapping stays inside hosted Review. There is no public API for creating, updating, or applying mappings.

2. Upload the file

The 201 response includes an upload object with a pre-signed url, the headers to send, and the method (PUT). Upload the raw file bytes with exactly those headers. The URL expires after 30 minutes.

Object storage notifies Transmutify when the upload completes and the run advances automatically — no extra API call needed. Structured uploads use the 50 MB file limit; image uploads use the 10 MB image limit.

3. Review and refine the mapping

After the upload, Transmutify inspects the file (header detection, column extraction, sample rows) and — if a provider is set — asks it to prepare the mapping. For image files, Transmutify sends the uploaded image to the provider, writes the generated rows, and opens the hosted review directly on Validate Data. Send reviewers to the hosted review_url returned by the create or full transformation response. The Review UI handles review readiness, review failures, mapping edits, data validation, and approval. Poll GET /transformations/{id} only when you need to refresh your own integration state. The full transformation response includes:

  • mapping_rule — target field name → source column header (or null for unmapped fields).
  • source_headers and input_has_header — what was detected in the file.
Only a small, sanitized sample reaches the AI. For structured files, preparing the mapping uses just the column headers and a few sample rows, and detected PII (emails, phone numbers, IBANs, card and tax numbers) is replaced with format-preserving fakes before sending, so the AI sees each value's shape but not its real contents. Approving the review then transforms the first 100,000 uploaded records locally, with no further AI calls — the bulk of your data never leaves Transmutify for the provider.
Image extraction is different from structured-file mapping: the uploaded image is sent to your configured provider so it can extract visible records. Only upload images you are permitted to share with that provider.

Reviewers regenerate or override mappings, correct header detection, edit source data, and approve from inside the hosted Review UI. These review actions are intentionally not exposed as customer API endpoints.

4. Approve the review

When the data looks right, the reviewer approves inside the hosted Review UI. Transmutify locks the latest valid mapping and saved data edits, switches the run to the final stage, and processes the configured row window.

The transformation.finished webhook fires when final output completes successfully. If you need live progress or failure details, processed_rows / total_rows and the persisted error payload are available on the run, and GET /transformations/{id} is the polling fallback.

5. Download the output

The successful transformation.finished webhook payload includes the pre-signed download_url directly. Without a webhook, fetch the run once status is completed in the final stage. Download links are valid for 60 minutes per request — fetch the run again for a fresh link. The artifact is retained until file_retention_until, 7 days after completion.

Download links expire and output files are deleted after the retention window. Fetch and store the artifact on your side as soon as the run completes.