[Transformations] Transform an uploaded file.
Upload a multipart file and run an existing transformation on it (instead of
refreshing a dynamic source). The run is asynchronous — poll the status endpoint
with the returned automation UUID. If an email is provided, a success/error report
is sent to it on completion. For uploaded-file runs, original_file in the status
response is always null — an upload isn't backed up as a downloadable source.
sequenceDiagram
title Running and following a transformation
participant f as Front
participant b as Back
f ->> b: Trigger a new transformation [1]
f ->> b: Get transformation status [2]
https://api.wetransform.com/transformation/automation/{transformationId}/upload
| Parameter | Description |
|---|---|
{transformationId} |
The transformation UUID to run on the uploaded file |
File uploads must use the regular HTTP multipart/form-data body encoding.
Multipart request carrying the source file to transform.
The optional email field (to notify with the success/error report) isn't
declared here: UploadExtractor requires every property of an
UploadInterface facade to be an UploadedFile (or a collection of them),
since multipart can't carry both a JSON body and file fields through the
BaseFacade docs system. Non-file form fields are read directly from the
request in the controller (see TemplateScaffolderController for the same
pattern).
| Field name | Description | Constraints | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| file |
The source file to transform, in the format the transformation expects. |
|
||||||||
success
boolean
Always true on successful responses.
true
payload
object
Payload of the requested resource.
payload.automation_id
*
string
The transformation tracking UUID.
"62986251-8ccb-4eb1-8730-e29e82c756d9"
payload.type
*
string
The type of automation that is being tracked.
"schedule"
payload.step
*
string
The step at which the transformation is at.
Possible values: pending, to_download, downloading, downloaded, to_normalize, normalizing, normalized, to_review, reviewed, to_parse, parsing, parsed, to_select, selected, reusing, to_import, importing, imported, to_create, creating, created, to_match, matching, matched, to_transform, transforming, transformed, to_submit, submitting, processed, failed
"pending"
payload.step_for_humans
*
object
The human-readable step at which the transformation is at.
payload.step_for_humans.code
string
A translation key for the given message.
"source.event.pending"
payload.step_for_humans.message
string
The translated version of the message.
Click on "Example" to get its translated value.
payload.details
*
string
The transformation step details.
If an error happened, this field will contain the error message.
"The transformation is pending."
payload.original_file
*
string
The URL at which can be found the original file fetched when the transformation was started.
"https:\/\/example.com\/original-file.csv"
payload.transformed_file
*
string
The URL at which can be found the transformed file.
"https:\/\/example.com\/transformed-file.csv"
payload.error_report_file
*
string
The URL at which can be found the error report file, if any.
"https:\/\/example.com\/error-report-file.csv"
payload.created_at
datetime
The date at which the transformation was initiated.
product
*
object
A product needed.
Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.
product.requirement
*
string
Whether the user requested a features s/he doesn't have access to,
or the user needs greater limits.
Possible values: permission, limitation
"permission"
product.permission
*
object
The required permission.
You will need to know which permission is needed in order to fill up search filters in the shop.
product.permission.description
*
string
A human-understandable name for the permission.
product.permission.name
string
A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).
Possible values depend on the context, check the domain's metadata endpoint.
"X_SOURCE_FORMAT_XML"
product.limitation_type
*
string
The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value
*
integer
The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).
product.limitation_current_value
*
integer
The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).
product.limitation_object
*
object
The limitation type in a readable format, for example, "lines per file".
product.is_cta
*
boolean
Whether a Call To Action should be displayed.
It may not be displayed if:
- the limitation is on the membership role
- the limitation is on the customer role
- the user is a sender
debug
array
Debug information.
Contains logs about business logic explaining state of the response payload.
Provided in development & admin modes only.
* are nullable.
{
"success": true,
"payload": {
"automation_id": "62986251-8ccb-4eb1-8730-e29e82c756d9",
"type": "schedule",
"step": "pending",
"step_for_humans": {
"code": "source.event.pending",
"message": "Process execution queued."
},
"details": "The transformation is pending.",
"original_file": "https:\/\/example.com\/original-file.csv",
"transformed_file": "https:\/\/example.com\/transformed-file.csv",
"error_report_file": "https:\/\/example.com\/error-report-file.csv",
"created_at": "2026-09-02T18:45:14+00:00"
},
"product": {
"requirement": "permission",
"permission": {
"name": "X_SOURCE_FORMAT_XML",
"description": "Can import XML files"
},
"limitation_type": null,
"limitation_needed_value": null,
"limitation_current_value": null,
"limitation_object": null,
"is_cta": false
},
"debug": []
}User is well authenticated, but not authorized to access the resource.
It can happen if user is trying to use a feature that s/he didn't pay for, access someone else's resource, etc.
These issues are normally fixed by the frontend, which should render features and resources user has access to.
success
boolean
Always false on error responses.
false
payload
object
Context about the error, if any.
product
*
object
A product needed.
Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.
product.requirement
*
string
Whether the user requested a features s/he doesn't have access to,
or the user needs greater limits.
Possible values: permission, limitation
"permission"
product.permission
*
object
The required permission.
You will need to know which permission is needed in order to fill up search filters in the shop.
product.permission.description
*
string
A human-understandable name for the permission.
product.permission.name
string
A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).
Possible values depend on the context, check the domain's metadata endpoint.
"X_SOURCE_FORMAT_XML"
product.limitation_type
*
string
The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value
*
integer
The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).
product.limitation_current_value
*
integer
The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).
product.limitation_object
*
object
The limitation type in a readable format, for example, "lines per file".
product.is_cta
*
boolean
Whether a Call To Action should be displayed.
It may not be displayed if:
- the limitation is on the membership role
- the limitation is on the customer role
- the user is a sender
debug
array
Debug information.
Contains logs about business logic explaining state of the response payload.
Provided in development & admin modes only.
* are nullable.
{
"success": false,
"payload": [],
"product": {
"requirement": "permission",
"permission": {
"name": "X_SOURCE_FORMAT_XML",
"description": "Can import XML files"
},
"limitation_type": null,
"limitation_needed_value": null,
"limitation_current_value": null,
"limitation_object": null,
"is_cta": false
},
"debug": []
}