API documentation

Update a template

Partial update: omitted fields are left unchanged.

description, max_file_size, file_name and extension are cleared when sent as null. For the other fields, null means "unchanged".
user_metadata, when sent, replaces the whole list: entries you leave out are deleted.
Changing handle changes this template's URL in every endpoint and on the sender pages. It fails with 409 if another template already uses it.

PUT https://api.wetransform.com/template/{templateHandle}

URL Parameters

Parameter	Description
`{templateHandle}`	The template handle, e.g. `employees`, unique within your organisation.

Request Payload

Request

TemplatePublicTemplateRequest

name string

The template name, shown to your customers. Required on creation, and the source of the handle when handle is omitted.

Sample: "Peoply"

required on create max 70 characters

handle string

URL-safe identifier used in every template endpoint and in the sender page URL (https://<organisation-handle>.send-a-file.io/<template-handle>).

2 to 32 lowercase letters, digits and dashes. Optional on creation: derived from name, and suffixed with -2, -3… when another template already uses it.

Sample: "peoply"

2 to 32 characters pattern: ^[a-z0-9]([a-z0-9\-]+)?[a-z0-9]$ handle not blacklisted

description string

Explains to your customers what the template is for. Sending null clears it.

Sample: "Update your employees database at Peoply."

max 4096 characters

item string

What one row of the delivered file represents, as a singular noun (e.g. employee, product). Required on creation.

Sample: "employee"

required on create pattern: \w+ max 32 characters

format object

Delivered file format. Set format.format and the matching configuration object (e.g. format.csv for csv). Required on creation.

required on create

format.format string

The selected template format.

Possible values: csv, xml, json, xls, custom

Sample: "csv"

required one of: csv, xml, json, xls, custom

format.csv object

Always null if not granted Can create target formats in CSV

CSV settings (delimiter, encoding, header rows…). Read only when format is csv, and only filled for a CSV template in responses.

format.csv.bom string

The optional byte order mark.

It is used at the beginning of the CSV file in order to improve interoperability with programs interacting with CSV, but is rarely used.

Possible values: none, utf8, utf16_be, utf16_le, utf32_be, utf32_le

Sample: "none"

required one of: none, utf8, utf16_be, utf16_le, utf32_be, utf32_le

format.csv.delimiter string

The CSV delimiter.

Possible values: comma, semi_column, tab, pipe

Sample: "comma"

required one of: comma, semi_column, tab, pipe

format.csv.enclosure string

Character enclosing values that contain the delimiter, quotes or line breaks.

Possible values: double_quotes, single_quotes

Sample: "double_quotes"

required one of: double_quotes, single_quotes

format.csv.escape string

CSV escaping character.

Possible values: backslash, double_quote

Sample: "backslash"

required one of: backslash, double_quote

format.csv.newline string

CSV newline character(s).

Possible values: lf, cr, crlf

Sample: "lf"

required one of: lf, cr, crlf

format.csv.encoding string

CSV file encoding.

Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

Sample: "UTF-8"

required one of: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

format.csv.header string

The file header.

Sometimes, CSV begin with a multiline explanation and the column headers start at line 4 or 5 after that header.

max 4096 characters

format.csv.nb_headers integer

Number of times the column header row is written: 0 = no header row, 1 = one header row (usual), 2 = the header row written twice.

Sample: 1

required between 0 and 2

format.csv.no_empty_column boolean

Whether columns that are empty on every row are removed from the CSV file.

Sample: false

format.xml object

Always null if not granted Can create target formats in XML

XML settings (root and row element names). Read only when format is xml, and only filled for an XML template in responses.

format.xml.root string

The XML's root node.

XML data should start with an encapsulating root node.

Sample: "items"

required max 32 characters

format.xml.line string

One row's encapsulator.

Every row of the transformed data should be encapsulated in an XML node.

Sample: "item"

required max 32 characters

format.json object

Always null if not granted Can create target formats in JSON

JSON settings, including the payload tree each row is written with. Read only when format is json, and only filled for a JSON template in responses.

format.json.export_empty_values boolean

Export empty values.

{ "key": "", "another_key": null }

Sample: false

required

format.json.json_nodes array

The JSON payload structure: one tree, rendered once per data row.

When absent, each row is exported as a flat object carrying every template column.

valid json nodes

format.json.json_nodes[].id string

Your identifier for this node, e.g. a UUID. Only used, with parent_id, to find the root: it is not stored, so it may change from one call to the next.

Sample: "c325d437-af64-437b-b16b-85589e790956"

format.json.json_nodes[].parent_id string

Null on the root node, and on the root node only: json_nodes must hold exactly one root. Nesting itself is expressed with children.

format.json.json_nodes[].position integer

Order of the node among its siblings, lowest first: keys of an object and items of an array are written in that order.

Sample: 0

format.json.json_nodes[].omit_if_empty boolean

When true, the node is left out of its parent (key and all) if its value is empty for the row, instead of being written as null, "" or an empty object/array. Defaults to false.

Sample: false

format.json.json_nodes[].key string

Property name written in the parent object. Required when the parent is an object, forbidden when it is an array; ignored on the root.

format.json.json_nodes[].type string

What the node writes. object and array hold children and no value.

column writes the row's value of a template column, typed from that column's data type (number, boolean, string). json parses the value (or the column cell) as raw JSON. string, number, boolean and null write a constant.

Sample: "object"

one of: object, array, column, json, string, number, boolean, null

format.json.json_nodes[].value

For a column node, the technical name of the template column to read. For a constant (string, number, boolean, json), the value written on every row. Must be null on object and array nodes.

format.json.json_nodes[].children array

Nested nodes of an object or array node; leaf types cannot have children.

format.json.json_nodes[].children[].id string

Your identifier for this node, e.g. a UUID. Only used, with parent_id, to find the root: it is not stored, so it may change from one call to the next.

Sample: "ecdc0b9f-8ce0-40b0-abf7-c6bb73185af2"

format.json.json_nodes[].children[].parent_id string

Null on the root node, and on the root node only: json_nodes must hold exactly one root. Nesting itself is expressed with children.

Sample: "c325d437-af64-437b-b16b-85589e790956"

format.json.json_nodes[].children[].position integer

Order of the node among its siblings, lowest first: keys of an object and items of an array are written in that order.

Sample: 0

format.json.json_nodes[].children[].omit_if_empty boolean

When true, the node is left out of its parent (key and all) if its value is empty for the row, instead of being written as null, "" or an empty object/array. Defaults to false.

Sample: false

format.json.json_nodes[].children[].key string

Property name written in the parent object. Required when the parent is an object, forbidden when it is an array; ignored on the root.

Sample: "name"

format.json.json_nodes[].children[].type string

What the node writes. object and array hold children and no value.

Sample: "column"

one of: object, array, column, json, string, number, boolean, null

format.json.json_nodes[].children[].value

Sample: "last_name"

format.json.json_nodes[].children[].children array

Nested nodes of an object or array node; leaf types cannot have children.

format.xls object

Always null if not granted Can create target formats in XLS

Excel settings (sheet name). Read only when format is xls, and only filled for an Excel template in responses.

format.xls.sheet_name string

The worksheet name.

If left empty, the generated spreadsheet keeps its default sheet name. When provided, the worksheet is renamed accordingly. Excel forbids the characters \ / ? * : [ ] and a length above 31.

max 31 characters pattern: ^[^\\/?*:\[\]]*$

format.custom object

Always null if not granted Create a specific type for the target format

Custom format: Twig header, row and footer fragments rendering any text format.

Read only when format is custom, and only filled for a custom template in responses.

format.custom.encoding string

File encoding.

Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

Sample: "UTF-8"

one of: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

format.custom.header string

The "header" twig template.

It is located above the items, and can be used to generate the file header.

Sample: "<root>"

format.custom.item string

The "item" twig template.

We'll go through this template for every item to generate. The context available in the template contains "row", an array keyed by column name — read a value with row['<column name>'].

Sample: "<employee name=\"{{ row['name']|e('xml') }}\">{{ row['salary'] }}<\/employee>"

format.custom.footer string

The "footer" twig template.

It is located below the items, and can be used to generate the file footer.

Sample: "<\/root>"

format.custom.prettify boolean

Re-indent the generated file.

When true, the document rendered by the header, item and footer templates is re-indented before it is written, so the twig templates do not have to handle spacing themselves. The format is detected from the rendered document: one that starts with { or [ is rewritten as JSON (whitespace-only, every value copied verbatim), one that starts with < is re-serialized as UTF-8 XML (values, CDATA sections and empty-element shapes are kept, but equivalent forms may be normalized: character references are resolved to their characters).

The rendered document must be valid for the detected format, and must be one of the two: otherwise the test endpoint reports a rendering error, and deliveries fall back to the raw rendering. Leave it false for CSV, fixed width, EDI or any flat text.

Sample: true

enabled boolean

Whether customers can use the template. Defaults to true.

Sample: true

access_type string

The template's access type:

public when the template is accessible by anyone
restricted when the template is accessible by invited customers only

Defaults to restricted. Possible values: public, restricted

Sample: "public"

one of: public, restricted

accept_errors boolean

Whether rows that still fail a constraint are delivered. When false, those rows are removed from the delivered file. Defaults to true.

Sample: false

max_file_size integer

Maximum size, in bytes, of the delivered file (1 KiB to 50 MiB). A submission producing a larger file fails. null means no limit.

Sample: 5242880

between 1024 and 52428800

file_name string

Name of the delivered file, without extension. When null, a name such as wetransform_<template-handle>_20260929 is generated.

It is used when a customer submits a file to you. It may contain a date tag written as {front_format}, e.g. "employees_{YYYY-MM-DD}", which is resolved when the file is produced. Date tags are always rendered in UTC, regardless of the receiver's local timezone.

Outside of a date tag, only letters, digits, ".", "_" and "-" are allowed.

A date tag does not make the name unique: for FTP/SFTP destinations, two submissions of the same template on the same day resolve to the same destination path and the second overwrites the first (only the {X} epoch format is unique per second).

Sample: "employees"

max 70 characters valid file name tokens

extension string

Extension of the delivered file, without the dot.

When null, the format's default extension is used. When empty, no extension is added to the file name.

Sample: "xml"

max 32 characters

export_empty_columns boolean

Whether columns that are empty on every row are kept in the delivered file. Defaults to true.

Treated as true for the JSON format and for templates with a push destination.

Sample: false

user_metadata array

Free key/value pairs you can filter templates on (GET /templates). When sent, replaces the whole list. Names must be unique.

unique property

user_metadata[].name string

Metadata key (max 32 characters).

Sample: "internal_code"

required 1 to 32 characters

user_metadata[].value string

Free text stored under that key (max 4096 characters), e.g. a category or your own reference. The template and customer listings can filter on it.

Sample: "TMPLT_001"

0 to 4096 characters

Properties suffixed with * are nullable.

{
    "name": "Peoply",
    "handle": "peoply",
    "description": "Update your employees database at Peoply.",
    "item": "employee",
    "enabled": true,
    "access_type": "public",
    "accept_errors": false,
    "max_file_size": 5242880,
    "file_name": "employees",
    "extension": "xml",
    "export_empty_columns": false,
    "format": {
        "format": "csv",
        "csv": {
            "bom": "none",
            "delimiter": "comma",
            "enclosure": "double_quotes",
            "escape": "backslash",
            "newline": "lf",
            "encoding": "UTF-8",
            "header": null,
            "nb_headers": 1,
            "no_empty_column": false
        },
        "xml": {
            "root": "items",
            "line": "item"
        },
        "json": {
            "export_empty_values": false,
            "json_nodes": [
                {
                    "id": "c325d437-af64-437b-b16b-85589e790956",
                    "parent_id": null,
                    "position": 0,
                    "omit_if_empty": false,
                    "key": null,
                    "type": "object",
                    "value": null,
                    "children": [
                        {
                            "id": "ecdc0b9f-8ce0-40b0-abf7-c6bb73185af2",
                            "parent_id": "c325d437-af64-437b-b16b-85589e790956",
                            "position": 0,
                            "omit_if_empty": false,
                            "key": "name",
                            "type": "column",
                            "value": "last_name",
                            "children": []
                        }
                    ]
                }
            ]
        },
        "xls": {
            "sheet_name": null
        },
        "custom": {
            "encoding": "UTF-8",
            "header": "<root>",
            "item": "<employee name=\"{{ row['name']|e('xml') }}\">{{ row['salary'] }}<\/employee>",
            "footer": "<\/root>",
            "prettify": true
        }
    },
    "user_metadata": [
        {
            "name": "internal_code",
            "value": "TMPLT_001"
        },
        {
            "name": "department",
            "value": "hr"
        }
    ]
}

Copy

Responses

Response 200

ResponseSuccess TemplatePublicTemplateResponse

success boolean

Always true on successful responses.

Sample: true

payload object

Payload of the requested resource.

payload.template_handle string nullable

The template handle, used in every template endpoint URL.

Sample: "my-template"

payload.is_enabled boolean

Whether customers can use the template (enabled in requests).

Sample: true

payload.name string nullable

The template name, shown to your customers.

Sample: "Employee Leaves (RE)"

payload.description string nullable

Explains to your customers what the template is for.

Sample: "Upload your employee leaves and absences, automate calendar updates and email..." (truncated)

payload.item string nullable

What one row of the delivered file represents (e.g. employee).

Sample: "leave"

payload.access_type string nullable

public: any of your customers can use the template; restricted: only the customers granted it.

Sample: "restricted"

payload.accept_errors boolean nullable

Whether rows that still fail a constraint are delivered. When false, those rows are removed from the delivered file.

Sample: false

payload.max_file_size integer nullable

Maximum size, in bytes, of the delivered file. null means no limit.

Sample: 5242880

payload.file_name string nullable

Name of the delivered file, without extension. null when not set.

Returned with its date tags (if any) unresolved — the exact stored value, not the name a produced file would have.

Sample: "leaves"

payload.extension string nullable

The delivered file extension. null means the format's default; empty means none.

Sample: "csv"

payload.export_empty_columns boolean nullable

Whether columns that are empty on every row are kept in the delivered file. Treated as true for the JSON format and for templates with a push destination.

Sample: false

payload.format object nullable

Delivered file format configuration.

payload.format.format string

The selected template format.

Possible values: csv, xml, json, xls, custom

Sample: "csv"

payload.format.csv object nullable

Always null if not granted Can create target formats in CSV

CSV settings (delimiter, encoding, header rows…). Read only when format is csv, and only filled for a CSV template in responses.

payload.format.csv.bom string

The optional byte order mark.

It is used at the beginning of the CSV file in order to improve interoperability with programs interacting with CSV, but is rarely used.

Possible values: none, utf8, utf16_be, utf16_le, utf32_be, utf32_le

Sample: "none"

payload.format.csv.delimiter string

The CSV delimiter.

Possible values: comma, semi_column, tab, pipe

Sample: "comma"

payload.format.csv.enclosure string

Character enclosing values that contain the delimiter, quotes or line breaks.

Possible values: double_quotes, single_quotes

Sample: "double_quotes"

payload.format.csv.escape string

CSV escaping character.

Possible values: backslash, double_quote

Sample: "backslash"

payload.format.csv.newline string

CSV newline character(s).

Possible values: lf, cr, crlf

Sample: "lf"

payload.format.csv.encoding string

CSV file encoding.

Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

Sample: "UTF-8"

payload.format.csv.header string nullable

The file header.

Sometimes, CSV begin with a multiline explanation and the column headers start at line 4 or 5 after that header.

payload.format.csv.nb_headers integer

Number of times the column header row is written: 0 = no header row, 1 = one header row (usual), 2 = the header row written twice.

Sample: 1

payload.format.csv.no_empty_column boolean nullable

Whether columns that are empty on every row are removed from the CSV file.

Sample: false

payload.format.xml object nullable

Always null if not granted Can create target formats in XML

XML settings (root and row element names). Read only when format is xml, and only filled for an XML template in responses.

payload.format.xml.root string

The XML's root node.

XML data should start with an encapsulating root node.

Sample: "items"

payload.format.xml.line string

One row's encapsulator.

Every row of the transformed data should be encapsulated in an XML node.

Sample: "item"

payload.format.json object nullable

Always null if not granted Can create target formats in JSON

JSON settings, including the payload tree each row is written with. Read only when format is json, and only filled for a JSON template in responses.

payload.format.json.export_empty_values boolean nullable

Export empty values.

{ "key": "", "another_key": null }

Sample: false

payload.format.json.json_nodes array nullable

The JSON payload structure: one tree, rendered once per data row.

When absent, each row is exported as a flat object carrying every template column.

payload.format.json.json_nodes[].id string nullable

Your identifier for this node, e.g. a UUID. Only used, with parent_id, to find the root: it is not stored, so it may change from one call to the next.

Sample: "0fe42ebb-6427-4a78-8221-30a52b1bcc9f"

payload.format.json.json_nodes[].parent_id string nullable

Null on the root node, and on the root node only: json_nodes must hold exactly one root. Nesting itself is expressed with children.

payload.format.json.json_nodes[].position integer nullable

Order of the node among its siblings, lowest first: keys of an object and items of an array are written in that order.

Sample: 0

payload.format.json.json_nodes[].omit_if_empty boolean nullable

When true, the node is left out of its parent (key and all) if its value is empty for the row, instead of being written as null, "" or an empty object/array. Defaults to false.

Sample: false

payload.format.json.json_nodes[].key string nullable

Property name written in the parent object. Required when the parent is an object, forbidden when it is an array; ignored on the root.

payload.format.json.json_nodes[].type string nullable

What the node writes. object and array hold children and no value.

Sample: "object"

payload.format.json.json_nodes[].value nullable

payload.format.json.json_nodes[].children array nullable

Nested nodes of an object or array node; leaf types cannot have children.

payload.format.json.json_nodes[].children[].id string nullable

Your identifier for this node, e.g. a UUID. Only used, with parent_id, to find the root: it is not stored, so it may change from one call to the next.

Sample: "56c4a618-9869-4493-884b-c2bd834a22c5"

payload.format.json.json_nodes[].children[].parent_id string nullable

Null on the root node, and on the root node only: json_nodes must hold exactly one root. Nesting itself is expressed with children.

Sample: "0fe42ebb-6427-4a78-8221-30a52b1bcc9f"

payload.format.json.json_nodes[].children[].position integer nullable

Order of the node among its siblings, lowest first: keys of an object and items of an array are written in that order.

Sample: 0

payload.format.json.json_nodes[].children[].omit_if_empty boolean nullable

When true, the node is left out of its parent (key and all) if its value is empty for the row, instead of being written as null, "" or an empty object/array. Defaults to false.

Sample: false

payload.format.json.json_nodes[].children[].key string nullable

Property name written in the parent object. Required when the parent is an object, forbidden when it is an array; ignored on the root.

Sample: "name"

payload.format.json.json_nodes[].children[].type string nullable

What the node writes. object and array hold children and no value.

Sample: "column"

payload.format.json.json_nodes[].children[].value nullable

Sample: "last_name"

payload.format.json.json_nodes[].children[].children array nullable

Nested nodes of an object or array node; leaf types cannot have children.

payload.format.xls object nullable

Always null if not granted Can create target formats in XLS

Excel settings (sheet name). Read only when format is xls, and only filled for an Excel template in responses.

payload.format.xls.sheet_name string nullable

The worksheet name.

If left empty, the generated spreadsheet keeps its default sheet name. When provided, the worksheet is renamed accordingly. Excel forbids the characters \ / ? * : [ ] and a length above 31.

payload.format.custom object nullable

Always null if not granted Create a specific type for the target format

Custom format: Twig header, row and footer fragments rendering any text format.

Read only when format is custom, and only filled for a custom template in responses.

payload.format.custom.encoding string nullable

File encoding.

Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh

Sample: "UTF-8"

payload.format.custom.header string nullable

The "header" twig template.

It is located above the items, and can be used to generate the file header.

Sample: "<root>"

payload.format.custom.item string nullable

The "item" twig template.

We'll go through this template for every item to generate. The context available in the template contains "row", an array keyed by column name — read a value with row['<column name>'].

Sample: "<employee name=\"{{ row['name']|e('xml') }}\">{{ row['salary'] }}<\/employee>"

payload.format.custom.footer string nullable

The "footer" twig template.

It is located below the items, and can be used to generate the file footer.

Sample: "<\/root>"

payload.format.custom.prettify boolean

Re-indent the generated file.

Sample: true

payload.picture_url string nullable

URL of the template picture (thumbnail). null when the template has none.

Sample: "https:\/\/api.wetransform.com\/icon.png"

payload.user_metadata array

Free key/value pairs you can filter templates on (GET /templates).

payload.user_metadata[].name string

Metadata key (max 32 characters).

Sample: "type"

payload.user_metadata[].value string nullable

Free text stored under that key (max 4096 characters), e.g. a category or your own reference. The template and customer listings can filter on it.

Sample: "human_resources"

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

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

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

Properties suffixed with * are nullable.

{
    "success": true,
    "payload": {
        "template_handle": "my-template",
        "is_enabled": true,
        "name": "Employee Leaves (RE)",
        "description": "Upload your employee leaves and absences, automate calendar updates and email notifications",
        "item": "leave",
        "access_type": "restricted",
        "accept_errors": false,
        "max_file_size": 5242880,
        "file_name": "leaves",
        "extension": "csv",
        "export_empty_columns": false,
        "format": {
            "format": "csv",
            "csv": {
                "bom": "none",
                "delimiter": "comma",
                "enclosure": "double_quotes",
                "escape": "backslash",
                "newline": "lf",
                "encoding": "UTF-8",
                "header": null,
                "nb_headers": 1,
                "no_empty_column": false
            },
            "xml": {
                "root": "items",
                "line": "item"
            },
            "json": {
                "export_empty_values": false,
                "json_nodes": [
                    {
                        "id": "0fe42ebb-6427-4a78-8221-30a52b1bcc9f",
                        "parent_id": null,
                        "position": 0,
                        "omit_if_empty": false,
                        "key": null,
                        "type": "object",
                        "value": null,
                        "children": [
                            {
                                "id": "56c4a618-9869-4493-884b-c2bd834a22c5",
                                "parent_id": "0fe42ebb-6427-4a78-8221-30a52b1bcc9f",
                                "position": 0,
                                "omit_if_empty": false,
                                "key": "name",
                                "type": "column",
                                "value": "last_name",
                                "children": []
                            }
                        ]
                    }
                ]
            },
            "xls": {
                "sheet_name": null
            },
            "custom": {
                "encoding": "UTF-8",
                "header": "<root>",
                "item": "<employee name=\"{{ row['name']|e('xml') }}\">{{ row['salary'] }}<\/employee>",
                "footer": "<\/root>",
                "prettify": true
            }
        },
        "picture_url": "https:\/\/api.wetransform.com\/icon.png",
        "user_metadata": [
            {
                "name": "type",
                "value": "human_resources"
            },
            {
                "name": "sub_type",
                "value": "human_resources"
            }
        ]
    },
    "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": []
}

Copy

Response 404 Unknown template handle.

ResponseError HttpNotFound

success boolean

Always false on error responses.

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

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

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

product.message object nullable

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.

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,
        "ai_feature": null,
        "message": null
    },
    "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 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

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

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

product.message object nullable

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.

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,
        "ai_feature": null,
        "message": null
    },
    "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 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

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

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

product.message object nullable

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.

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,
        "ai_feature": null,
        "message": null
    },
    "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 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

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

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

product.message object nullable

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.

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,
        "ai_feature": null,
        "message": null
    },
    "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

Generic message saying the request contains invalid values, translated in the request locale. The details are in violations.

payload.error.code string

A translation key for the given message.

Sample: "exception.violation"

payload.error.message string object

The translated version of the message.

Click on "Example" to get its translated value.

payload.violations array

One entry per invalid value: the property path (e.g. format.csv.delimiter) and the reason. Several entries can target the same property.

payload.violations[].property_path string

Property having an invalid value.

Sample: "title"

payload.violations[].invalid_value nullable

The invalid value.

Sample: ""

payload.violations[].message string

An error message describing the violation.

Sample: "This value should not be blank"

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

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

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

product.message object nullable

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.

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,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}

Copy

Back to API Reference

Interactive Console

Please login in order to access the console.