Read a submission
Returns one submission with its row counts and signed links to its files (valid 30 days, no authentication needed).
https://api.wetransform.com/sender/submission/{submissionId}
| Parameter | Description | Pattern |
|---|---|---|
{submissionId} |
UUID of the submission to read ( |
[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12} |
success
boolean
Always true on successful responses.
true
payload
object
Payload of the requested resource.
payload.connector
object
nullable
The connector behind this submission's transformation (itself if it is a connector, else the connector it was made from), for showing its name and logo. Null when neither applies.
payload.connector.is_connector
boolean
Whether the transformation is itself a connector (vs. made from one).
false
payload.connector.changed
boolean
Whether the connector was edited after this transformation was made from it, i.e. an update is available. Always false when the transformation is itself a connector.
true
payload.connector.connector_id
string
nullable
UUID of the connector (a connector is itself a transformation).
"5450e6b1-d206-42ee-8e87-9ead7061435e"
payload.connector.name
string
nullable
The connector's display name (e.g. "Sage").
"Sage"
payload.connector.picture_url
string
nullable
Public URL of the connector's logo thumbnail, if any.
"https:\/\/example.com\/connector.thumbnail.png"
payload.submission_id
string
nullable
UUID of the submission. Pass it to GET /sender/submission/{submissionId}.
"1f349d34-83fc-4004-9f70-eb0cc38aa30f"
payload.customer_id
string
nullable
External ID of the customer who submitted, as set by the receiver (not the customer UUID).
"jojo"
payload.customer_name
string
nullable
Name of the customer who submitted, as it was at submission time.
"Jo\u00ebl"
payload.customer_email
string
nullable
Email of the customer who submitted, as it was at submission time.
"joel@fuz.org"
payload.source_id
string
nullable
The source UUID
"dc9ac839-d5fd-4a5c-ae82-4c90c5e3b74c"
payload.source_name
string
nullable
Name of the source file that was transformed.
"New Hires"
payload.source_file_url
string
nullable
Signed link (valid 30 days) to the source file exactly as it was received. Null once the file was purged.
"https:\/\/example.com\/source.xlsx"
payload.normalized_source_file
string
nullable
Signed link (valid 30 days) to the source converted to CSV, before any transformation step. Null once the file was purged.
"https:\/\/example.com\/normalized-source.csv"
payload.target_file_url
string
nullable
Signed link (valid 30 days) to the submitted file. Null while the submission is in progress, when it failed, or once the file was purged.
"https:\/\/example.com\/target.csv"
payload.error_report_url
string
nullable
Signed link (valid 30 days) to a CSV with one line per validation error. Null when no row failed validation.
"https:\/\/example.com\/error-report.csv"
payload.push_report_url
string
nullable
deprecated
The first push report's url. Deprecated: a submission keeps one report
per push exporter, read push_reports.
"https:\/\/example.com\/push-report.csv"
payload.push_reports
array
One report per push exporter that fired on the submission, in firing order. Only exposed to the receiver's organisation.
payload.push_reports[].exporter_id
string
nullable
The push exporter's UUID; null for a report stored before reports were kept per exporter.
"38e5355b-a8db-4a5f-8e98-1afdcbded8cc"
payload.push_reports[].exporter_name
string
nullable
The push exporter's name when it fired (kept after a rename or a deletion); null when the exporter had none, or for a legacy report.
"Shopify API"
payload.push_reports[].url
string
nullable
The report's CSV download URL.
"https:\/\/example.com\/push-report.csv"
payload.invalid_rows_url
string
nullable
The URL of the CSV holding the rows that failed validation, exactly as
they stand in the target file (target columns, one record per failing
row, no violation message), if any row failed. Unlike
error_report_url, which lists one record per violation, this file is
the data itself.
"https:\/\/example.com\/invalid-rows.csv"
payload.download_url
string
nullable
Permanent link to the transformation's latest submitted file (not necessarily this submission's). Null unless the template exposes files.
"https:\/\/example.com\/download.csv"
payload.target_name
string
nullable
File name of the submitted file.
payload.template_name
string
nullable
Name of the template the file was transformed into, as it was at submission time.
"New Hires"
payload.template_item
string
nullable
What one row represents, as set on the template (e.g. Employee), to label the row
counts.
"Employee"
payload.template_picture_url
string
nullable
Public URL of the template's picture thumbnail. Null when the template has no picture.
"https:\/\/example.com\/picture.png"
payload.rows_in_source
integer
nullable
Number of data rows read from the source file.
100
payload.rows_ignored_from_source
integer
nullable
Number of source rows ignored at import. Currently always 0.
0
payload.columns_ignored_from_source
integer
nullable
Number of source columns ignored at import, beyond maximum_number_of_columns.
0
payload.maximum_number_of_columns
integer
Maximum number of source columns WeTransform reads. A platform limit, identical for every submission.
1016
payload.rows_in_target
integer
nullable
Number of rows written to the submitted file.
100
payload.rows_in_error
integer
nullable
Number of rows that failed at least one validation rule. They are left out of the submitted file unless the template accepts errors.
12
payload.rows_ignored_from_target
integer
nullable
Number of rows left out of the submitted file because the organisation ran out of line credits.
0
payload.created_at
datetime
nullable
When the submission was started.
payload.pushed_at
datetime
nullable
When the receiver was told the file was ready (a push completed or the
READY_FOR_DOWNLOAD webhook fired). Null otherwise; it does not imply a push is set up.
payload.failed
boolean
Whether the submission failed (error_message then says why). A submission still in
progress reports false with no target_file_url yet.
false
payload.error_message
string
nullable
Why the submission failed. Null unless failed is true.
product
object
nullable
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
nullable
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
nullable
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
nullable
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
nullable
The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value
integer
nullable
The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).
product.limitation_current_value
integer
nullable
The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).
product.limitation_object
object
nullable
The limitation type in a readable format, for example, "lines per file".
product.ai_feature
string
nullable
The AI feature that could not run, when an AI feature is what hit the limitation
(null for any other product).
Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context
product.message
object
nullable
What stopped, on what, and what it would take — translated and ready to display,
with one wording per AI feature: "Matching the values of column «Couleur» with AI
needs 12 AI credits, and 10 are left."
Null whenever ai_feature is, and on the rare AI exposure that has no subject to
name (the template collection's json_column_match_product covers no single
template). Fall back to the generic call-to-action then.
product.is_cta
boolean
nullable
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": {
"connector": {
"is_connector": false,
"changed": true,
"connector_id": "5450e6b1-d206-42ee-8e87-9ead7061435e",
"name": "Sage",
"picture_url": "https:\/\/example.com\/connector.thumbnail.png"
},
"submission_id": "1f349d34-83fc-4004-9f70-eb0cc38aa30f",
"customer_id": "jojo",
"customer_name": "Jo\u00ebl",
"customer_email": "joel@fuz.org",
"source_id": "dc9ac839-d5fd-4a5c-ae82-4c90c5e3b74c",
"source_name": "New Hires",
"source_file_url": "https:\/\/example.com\/source.xlsx",
"normalized_source_file": "https:\/\/example.com\/normalized-source.csv",
"target_file_url": "https:\/\/example.com\/target.csv",
"error_report_url": "https:\/\/example.com\/error-report.csv",
"push_report_url": "https:\/\/example.com\/push-report.csv",
"push_reports": [
{
"exporter_id": "38e5355b-a8db-4a5f-8e98-1afdcbded8cc",
"exporter_name": "Shopify API",
"url": "https:\/\/example.com\/push-report.csv"
}
],
"invalid_rows_url": "https:\/\/example.com\/invalid-rows.csv",
"download_url": "https:\/\/example.com\/download.csv",
"target_name": null,
"template_name": "New Hires",
"template_item": "Employee",
"template_picture_url": "https:\/\/example.com\/picture.png",
"rows_in_source": 100,
"rows_ignored_from_source": 0,
"columns_ignored_from_source": 0,
"maximum_number_of_columns": 1016,
"rows_in_target": 100,
"rows_in_error": 12,
"rows_ignored_from_target": 0,
"created_at": "2020-12-31T23:59:55+00:00",
"pushed_at": "2021-01-01T00:00:00+00:00",
"failed": false,
"error_message": null
},
"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,
"ai_feature": null,
"message": null
},
"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
nullable
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
nullable
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
nullable
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
nullable
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
nullable
The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value
integer
nullable
The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).
product.limitation_current_value
integer
nullable
The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).
product.limitation_object
object
nullable
The limitation type in a readable format, for example, "lines per file".
product.ai_feature
string
nullable
The AI feature that could not run, when an AI feature is what hit the limitation
(null for any other product).
Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context
product.message
object
nullable
What stopped, on what, and what it would take — translated and ready to display,
with one wording per AI feature: "Matching the values of column «Couleur» with AI
needs 12 AI credits, and 10 are left."
Null whenever ai_feature is, and on the rare AI exposure that has no subject to
name (the template collection's json_column_match_product covers no single
template). Fall back to the generic call-to-action then.
product.is_cta
boolean
nullable
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,
"ai_feature": null,
"message": null
},
"debug": []
}