API documentation

[Submission] Read a submission by its download URL.

Authenticated customer

GET https://api.wetransform.com/sender/submission

Request Payload

Request

SubmissionPublicDownloadUrlRequest

download_url string

The absolute download URL.

Sample: "https:\/\/example.com\/download"

not blank url

{
    "download_url": "https:\/\/example.com\/download"
}

Copy

Responses

Response 200

ResponseSuccess Submission

success boolean

Always true on successful responses.

Sample: true

payload object

Payload of the requested resource.

payload.submission_id ^* string

The submission UUID

Sample: "0e33521c-85b7-4a2f-b7f1-48348d00db8d"

payload.customer_id ^* string

The customer external ID

Sample: "jojo"

payload.customer_name ^* string

The customer name

Sample: "Jo\u00ebl"

payload.customer_email ^* string

The customer email

Sample: "joel@fuz.org"

payload.source_id ^* string

The source UUID

Sample: "e4406ce0-3f4d-4d99-8bbf-da86e104cc19"

payload.source_name ^* string

The source name

Sample: "New Hires"

payload.source_file_url ^* string

The source file URL, if it still exists

Sample: "https:\/\/example.com\/source.csv"

payload.target_file_url ^* string

The target file URL

Sample: "https:\/\/example.com\/target.csv"

payload.error_report_url ^* string

The error report url.

Sample: "https:\/\/example.com\/error-report.csv"

payload.push_report_url ^* string

The push report url.

Sample: "https:\/\/example.com\/push-report.csv"

payload.download_url ^* string

The permanent download URL for this transformation's output file.

Sample: "https:\/\/example.com\/download.csv"

payload.target_name ^* string

The target file naem.

payload.template_name ^* string

The template name

Sample: "New Hires"

payload.template_item ^* string

The template item name

Useful to render the number of items in source, target, and errors.

Sample: "Employee"

payload.template_picture_url ^* string

The template picture URL, if any

Sample: "https:\/\/example.com\/picture.png"

payload.rows_in_source ^* integer

Number of rows that were imported from the source file.

Sample: 100

payload.rows_ignored_from_source ^* integer

Number of rows that were ignored in the source file.

Sample: 0

payload.columns_ignored_from_source ^* integer

Number of columns that were ignored in the source file.

Sample: 0

payload.maximum_number_of_columns integer

Maximum number of columns allowed.

Sample: 1016

payload.rows_in_target ^* integer

Number of rows in the target file.

Sample: 100

payload.rows_in_error ^* integer

Number of rows in error.

Sample: 12

payload.rows_ignored_from_target ^* integer

Number of rows truncated from the target file because of insufficient line credit.

Sample: 0

payload.created_at ^* datetime

The date at which the submission has been created.

payload.pushed_at ^* datetime

The date at which the receiver was notified that the submission's target file is ready — set either when the configured Push (HTTP request to the receiver's API) completes, or when the READY_FOR_DOWNLOAD webhook fires. Despite the name, this does NOT imply a Push integration is configured on the template.

payload.failed boolean

Whether the submission has failed.

Sample: false

payload.error_message ^* string

If the submission has failed, the error message.

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

Sample: "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.

Sample: "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

template_handle ^* string

Handle of the template currently in context, if any.

Many endpoints (and frontend components) require a template_handle. It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "new-hires"

source_id ^* string

UUID of the source currently in context, if any.

Many endpoints (and frontend components) require a source_id (the source UUID, not its database id). It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "9e7060d4-9314-4783-883a-8702471ccd39"

debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.

{
    "success": true,
    "payload": {
        "submission_id": "0e33521c-85b7-4a2f-b7f1-48348d00db8d",
        "customer_id": "jojo",
        "customer_name": "Jo\u00ebl",
        "customer_email": "joel@fuz.org",
        "source_id": "e4406ce0-3f4d-4d99-8bbf-da86e104cc19",
        "source_name": "New Hires",
        "source_file_url": "https:\/\/example.com\/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",
        "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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Response 400 Bad request.

ResponseError HttpBadRequest

The client sent an unexpected request.

It happens if the client sent an invalid JSON payload, or if the JSON payload cannot be mapped to the expected request object.

success boolean

Always false on error responses.

Sample: 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

Sample: "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.

Sample: "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

template_handle ^* string

Handle of the template currently in context, if any.

Many endpoints (and frontend components) require a template_handle. It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "new-hires"

source_id ^* string

UUID of the source currently in context, if any.

Sample: "9e7060d4-9314-4783-883a-8702471ccd39"

debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * 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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Response 401 Authentication required.

ResponseError HttpUnauthorized

User must be authenticated to access the resource.

This response is received when the authorization header does not contain a valid authentication token.

It mostly happens because the current access_token has expired, and it needs to be renewed using a refresh_token.

success boolean

Always false on error responses.

Sample: 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

Sample: "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.

Sample: "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

template_handle ^* string

Handle of the template currently in context, if any.

Many endpoints (and frontend components) require a template_handle. It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "new-hires"

source_id ^* string

UUID of the source currently in context, if any.

Sample: "9e7060d4-9314-4783-883a-8702471ccd39"

debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * 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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Response 403 Access denied.

ResponseError HttpForbidden

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.

Sample: 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

Sample: "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.

Sample: "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

template_handle ^* string

Handle of the template currently in context, if any.

Many endpoints (and frontend components) require a template_handle. It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "new-hires"

source_id ^* string

UUID of the source currently in context, if any.

Sample: "9e7060d4-9314-4783-883a-8702471ccd39"

debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * 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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Response 409 Payload contains invalid values.

ResponseError Violations Violation

A violation happens when a property value does not respect the expected constraints.

If a user is making a mistake in a form and frontend is not able to detect it (because of the constraint being tied to some business logic for example), the API will return the invalid properties with the right error messages.

Note: examples are hardcoded in english (no access to the translator in a DTO).

success boolean

Always false on error responses.

Sample: false

payload object

Context about the error, if any.

payload.error object

payload.error.code string

A translation key for the given message.

Sample: "exception.violation"

payload.error.message string

The translated version of the message.

Click on "Example" to get its translated value.

payload.violations array

payload.violations[].property_path string

Property having an invalid value.

Sample: "title"

payload.violations[].invalid_value ^*

The invalid value.

Sample: ""

payload.violations[].message string

An error message describing the violation.

Sample: "This value should not be blank"

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

Sample: "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.

Sample: "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

template_handle ^* string

Handle of the template currently in context, if any.

Many endpoints (and frontend components) require a template_handle. It is exposed here so consumers — most notably the AI agent — can reuse it instead of having to ask the user for it again.

Sample: "new-hires"

source_id ^* string

UUID of the source currently in context, if any.

Sample: "9e7060d4-9314-4783-883a-8702471ccd39"

debug array

Debug information.

Contains logs about business logic explaining state of the response payload.

Provided in development & admin modes only.

Properties suffixed with * are nullable.

{
    "success": false,
    "payload": {
        "error": {
            "code": "exception.violation",
            "message": "The provided payload contains property violations."
        },
        "violations": [
            {
                "property_path": "title",
                "invalid_value": "",
                "message": "This value should not be blank"
            },
            {
                "property_path": "price",
                "invalid_value": -5,
                "message": "The amount should be greater than 1"
            }
        ]
    },
    "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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Back to API Reference

Interactive Console

Please login in order to access the console.