List templates
Lists your organisation's templates (deleted ones excluded), most recently updated first, paginated.
Filters:
criteria: case-insensitive substring match on the handle, name or description. A space matches any sequence of characters.is_enabled:trueorfalseto keep only enabled or disabled templates. Omit it to get both.user_metadata: one or more{name, values}filters, sent asuser_metadata[0][name]=type&user_metadata[0][values]=hr,finance. A template must match every filter, and a filter matches when the template's metadata value is one of its comma-separatedvalues.
Send the optional X-Customer header (external ID, email or UUID of one of
your customers) to list only what that customer can use: public templates,
plus the restricted ones granted to it. An unknown customer returns 404.
https://api.wetransform.com/templates
is_enabled
boolean
Keep only enabled (true) or disabled (false) templates. Omit it to get both.
user_metadata
array
Filter on metadata: a result must match every entry.
Query-string form: user_metadata[0][name]=type&user_metadata[0][values]=hr,finance.
user_metadata[].name
string
Metadata key.
"type"
user_metadata[].values
string
Comma-separated values. The entry matches if the metadata value equals any of them (exact match).
"human_resources,finance"
page
integer
Page number to request, starting at 1. Defaults to 1.
1
per_page
integer
Number of entries per page, from 1 to 200. Defaults to 25.
25
criteria
string
Search criteria.
* are nullable.
{
"is_enabled": null,
"user_metadata": [
{
"name": "type",
"values": "human_resources,finance"
}
],
"page": 1,
"per_page": 25,
"criteria": null
}success
boolean
Always true on successful responses.
true
payload
object
Payload of the requested resource.
payload.total_pages
integer
Total number of available pages.
5
payload.current_page
integer
Current page requested.
5
payload.total_items
integer
Total number of items.
103
payload.items_per_page
integer
Number of items per page.
25
payload.entries
array
An array of the requested resources.
payload.entries[].template_handle
string
nullable
The template handle, used in every template endpoint URL.
"my-template"
payload.entries[].is_enabled
boolean
Whether customers can use the template (enabled in requests).
true
payload.entries[].name
string
nullable
The template name, shown to your customers.
"Employee Leaves (RE)"
payload.entries[].description
string
nullable
Explains to your customers what the template is for.
"Upload your employee leaves and absences, automate calendar updates and email..."
(truncated)
payload.entries[].item
string
nullable
What one row of the delivered file represents (e.g. employee).
"leave"
payload.entries[].access_type
string
nullable
public: any of your customers can use the template; restricted: only the customers granted it.
"restricted"
payload.entries[].accept_errors
boolean
nullable
Whether rows that still fail a constraint are delivered. When false, those rows are removed from the delivered file.
false
payload.entries[].max_file_size
integer
nullable
Maximum size, in bytes, of the delivered file. null means no limit.
5242880
payload.entries[].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.
"leaves"
payload.entries[].extension
string
nullable
The delivered file extension. null means the format's default; empty means none.
"csv"
payload.entries[].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.
false
payload.entries[].format
object
nullable
Delivered file format configuration.
payload.entries[].format.format
string
The selected template format.
Possible values: csv, xml, json, xls, custom
"csv"
payload.entries[].format.csv
object
nullable
CSV settings (delimiter, encoding, header rows…). Read only when format is
csv, and only filled for a CSV template in responses.
payload.entries[].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
"none"
payload.entries[].format.csv.delimiter
string
The CSV delimiter.
Possible values: comma, semi_column, tab, pipe
"comma"
payload.entries[].format.csv.enclosure
string
Character enclosing values that contain the delimiter, quotes or line breaks.
Possible values: double_quotes, single_quotes
"double_quotes"
payload.entries[].format.csv.escape
string
CSV escaping character.
Possible values: backslash, double_quote
"backslash"
payload.entries[].format.csv.newline
string
CSV newline character(s).
Possible values: lf, cr, crlf
"lf"
payload.entries[].format.csv.encoding
string
CSV file encoding.
Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh
"UTF-8"
payload.entries[].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.entries[].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.
1
payload.entries[].format.csv.no_empty_column
boolean
nullable
Whether columns that are empty on every row are removed from the CSV file.
false
payload.entries[].format.xml
object
nullable
XML settings (root and row element names). Read only when format is xml,
and only filled for an XML template in responses.
payload.entries[].format.xml.root
string
The XML's root node.
XML data should start with an encapsulating root node.
"items"
payload.entries[].format.xml.line
string
One row's encapsulator.
Every row of the transformed data should be encapsulated in an XML node.
"item"
payload.entries[].format.json
object
nullable
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.entries[].format.json.export_empty_values
boolean
nullable
Export empty values.
{ "key": "", "another_key": null }
false
payload.entries[].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.entries[].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.
"7c81e68e-1969-4a6e-8859-8f34bfac21ca"
payload.entries[].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.entries[].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.
0
payload.entries[].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.
false
payload.entries[].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.entries[].format.json.json_nodes[].type
string
nullable
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.
"object"
payload.entries[].format.json.json_nodes[].value
nullable
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.
payload.entries[].format.json.json_nodes[].children
array
nullable
Nested nodes of an object or array node; leaf types cannot have children.
payload.entries[].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.
"4023afe4-848a-4d6b-8cee-ae935da45518"
payload.entries[].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.
"7c81e68e-1969-4a6e-8859-8f34bfac21ca"
payload.entries[].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.
0
payload.entries[].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.
false
payload.entries[].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.
"name"
payload.entries[].format.json.json_nodes[].children[].type
string
nullable
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.
"column"
payload.entries[].format.json.json_nodes[].children[].value
nullable
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.
"last_name"
payload.entries[].format.json.json_nodes[].children[].children
array
nullable
Nested nodes of an object or array node; leaf types cannot have children.
payload.entries[].format.xls
object
nullable
Excel settings (sheet name). Read only when format is xls, and only filled
for an Excel template in responses.
payload.entries[].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.entries[].format.custom
object
nullable
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.entries[].format.custom.encoding
string
nullable
File encoding.
Possible values: UTF-8, LATIN1, ISO-8859-1, UTF-16, UTF-32, macintosh
"UTF-8"
payload.entries[].format.custom.header
string
nullable
The "header" twig template.
It is located above the items, and can be used to generate the file header.
"<root>"
payload.entries[].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>'].
"<employee name=\"{{ row['name']|e('xml') }}\">{{ row['salary'] }}<\/employee>"
payload.entries[].format.custom.footer
string
nullable
The "footer" twig template.
It is located below the items, and can be used to generate the file footer.
"<\/root>"
payload.entries[].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.
true
payload.entries[].picture_url
string
nullable
URL of the template picture (thumbnail). null when the template has none.
"https:\/\/api.wetransform.com\/icon.png"
payload.entries[].user_metadata
array
Free key/value pairs you can filter templates on (GET /templates).
payload.entries[].user_metadata[].name
string
Metadata key (max 32 characters).
"type"
payload.entries[].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.
"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
"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": {
"total_pages": 5,
"current_page": 5,
"total_items": 103,
"items_per_page": 25,
"entries": [
{
"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": "7c81e68e-1969-4a6e-8859-8f34bfac21ca",
"parent_id": null,
"position": 0,
"omit_if_empty": false,
"key": null,
"type": "object",
"value": null,
"children": [
{
"id": "4023afe4-848a-4d6b-8cee-ae935da45518",
"parent_id": "7c81e68e-1969-4a6e-8859-8f34bfac21ca",
"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"
}
]
},
{
"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": "686c68cf-9b2a-4bf4-95a5-54928e81907e",
"parent_id": null,
"position": 0,
"omit_if_empty": false,
"key": null,
"type": "object",
"value": null,
"children": [
{
"id": "666bfac3-6670-4a12-8c7f-6dd81e041656",
"parent_id": "686c68cf-9b2a-4bf4-95a5-54928e81907e",
"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"
}
]
},
{
"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": "d104d5de-c013-4b52-a078-770305ce5ab7",
"parent_id": null,
"position": 0,
"omit_if_empty": false,
"key": null,
"type": "object",
"value": null,
"children": [
{
"id": "87bb8da6-c7df-4f87-bfad-70ce3305346c",
"parent_id": "d104d5de-c013-4b52-a078-770305ce5ab7",
"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": []
}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": []
}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.
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": []
}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": []
}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.
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.
"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.
"title"
payload.violations[].invalid_value
nullable
The invalid value.
""
payload.violations[].message
string
An error message describing the violation.
"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
"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": {
"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": []
}