API documentation

[Template] Create a template.

Can manage all target formats

POST https://api.wetransform.com/template

Request Payload

Request

TemplatePublicTemplateRequest

name string

The template name.

Sample: "Peoply"

not blank Create length

handle ^* string

The template handle.

https://organisation-handle.send-a-file.io/template-handle

Sample: "peoply"

length regex handle not blacklisted

description ^* string

The template description.

Sample: "Update your employees database at Peoply."

length

item string

The item that represents one row in the target file.

Sample: "employee"

not blank Create regex length

format ^* object

The target file format configuration.

not null Create valid

format.format string

The selected template format.

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

Sample: "csv"

not blank format enum value format

format.csv ^* object

Always null if not granted Can create target formats in CSV

The CSV format configuration.

valid format

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"

not blank format enum value format

format.csv.delimiter string

The CSV delimiter

Possible values: comma, semi_column, tab, pipe

Sample: "comma"

not blank format enum value format

format.csv.enclosure string

The CSV enclosure.

The thing is, nobody use something else than double quotes yet, so the enum only contains double quotes... I leave the door open for adding new values, though.

Possible values: double_quotes, single_quotes

Sample: "double_quotes"

not blank format enum value format

format.csv.escape string

CSV escaping character.

Possible values: backslash, double_quote

Sample: "backslash"

not blank format enum value format

format.csv.newline string

CSV newline character(s).

Possible values: lf, cr, crlf

Sample: "lf"

not blank format enum value format

format.csv.encoding string

CSV file encoding.

We only kept most useful encodings, but may add new ones in the future.

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

Sample: "UTF-8"

not blank format enum value format

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.

length format

format.csv.nb_headers integer

Whether we should repeat column headers.

Sample: 1

not blank format range format

format.csv.no_empty_column ^* boolean

Whether we should remove empty columns when writing the CSV file.

Sample: false

format.xml ^* object

Always null if not granted Can create target formats in XML

The XML format configuration.

valid format

format.xml.root string

The XML's root node.

XML data should start with an encapsulating root node.

Sample: "items"

not blank format length format

format.xml.line string

One row's encapsulator.

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

Sample: "item"

not blank format length format

format.json ^* object

Always null if not granted Can create target formats in JSON

The JSON format configuration.

valid format

format.json.export_empty_values ^* boolean

Export empty values.

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

Sample: false

not null format

format.xls ^* object

Always null if not granted Can create target formats in XLS

The XLS format configuration.

valid format

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.

length format regex format

format.custom ^* object

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

The custom format configuration.

valid format

format.custom.encoding ^* string

File encoding.

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

Sample: "UTF-8"

enum value format

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 containing all column names as keys.

Sample: "<employee name=\"{{ column[\"name\"] }}\">{{ column[\"salary\"] }}<\/item>"

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

enabled ^* boolean

Whether the template can be used to perform transformations.

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

Possible values: public, restricted

Sample: "public"

enum value

accept_errors ^* boolean

Whether the receiver accepts to receive files containing errors.

Sample: false

max_file_size ^* integer

The maximum file size for this template, in bytes.

Sample: 5242880

range

file_name ^* string

An optional file name.

It will be used when submitting a file to the receiver.

Sample: "employees"

length

extension ^* string

An optional extension.

If not provided, the default format extension will be used. If provided but empty, no extension will be added to the file name.

Sample: "xml"

length

export_empty_columns ^* boolean

Whether the template should export empty columns.

Empty columns are columns that are empty in every row.

Sample: false

user_metadata ^* array

The template metadata.

valid unique property

user_metadata[].name string

Sample: "internal_code"

not blank length

user_metadata[].value ^* string

Sample: "TMPLT_001"

length

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
        },
        "xls": {
            "sheet_name": null
        },
        "custom": null
    },
    "user_metadata": [
        {
            "name": "internal_code",
            "value": "TMPLT_001"
        },
        {
            "name": "uuid",
            "value": "f4b3e2b5-4b2e-4d25-8f1b-2d1f2b3e4f5a"
        }
    ]
}

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

The template handle.

Sample: "my-template"

payload.is_enabled boolean

Whether the template is enabled.

Sample: true

payload.name ^* string

The template name.

Sample: "Employee Leaves (RE)"

payload.description ^* string

The template description.

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

payload.item ^* string

The item that represents one row in the target file.

Sample: "leave"

payload.access_type ^* string

The template's access type.

Sample: "restricted"

payload.accept_errors ^* boolean

Whether the receiver accepts to receive files containing errors.

Sample: false

payload.max_file_size ^* integer

The maximum file size for this template, in bytes.

Sample: 5242880

payload.file_name ^* string

An optional file name.

Sample: "leaves"

payload.extension ^* string

An optional extension.

Sample: "csv"

payload.export_empty_columns ^* boolean

Whether the template should export empty columns.

Sample: false

payload.format ^* object

The target file format configuration.

payload.format.format string

The selected template format.

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

Sample: "csv"

payload.format.csv ^* object

Always null if not granted Can create target formats in CSV

The CSV format configuration.

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

The CSV enclosure.

The thing is, nobody use something else than double quotes yet, so the enum only contains double quotes... I leave the door open for adding new values, though.

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.

We only kept most useful encodings, but may add new ones in the future.

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

Sample: "UTF-8"

payload.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.

payload.format.csv.nb_headers integer

Whether we should repeat column headers.

Sample: 1

payload.format.csv.no_empty_column ^* boolean

Whether we should remove empty columns when writing the CSV file.

Sample: false

payload.format.xml ^* object

Always null if not granted Can create target formats in XML

The XML format configuration.

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

Always null if not granted Can create target formats in JSON

The JSON format configuration.

payload.format.json.export_empty_values ^* boolean

Export empty values.

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

Sample: false

payload.format.xls ^* object

Always null if not granted Can create target formats in XLS

The XLS format configuration.

payload.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.

payload.format.custom ^* object

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

The custom format configuration.

payload.format.custom.encoding ^* string

File encoding.

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

Sample: "UTF-8"

payload.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>"

payload.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 containing all column names as keys.

Sample: "<employee name=\"{{ column[\"name\"] }}\">{{ column[\"salary\"] }}<\/item>"

payload.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>"

payload.picture_url ^* string

Profile picture's URL.

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

payload.user_metadata array

The template metadata.

payload.user_metadata[].name string

Sample: "type"

payload.user_metadata[].value ^* string

Sample: "human_resources"

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": {
        "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
            },
            "xls": {
                "sheet_name": null
            },
            "custom": null
        },
        "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
    },
    "template_handle": "new-hires",
    "source_id": "9e7060d4-9314-4783-883a-8702471ccd39",
    "debug": []
}

Copy

Response 402 Organisation cannot have more than N templates.

ResponseError ProductPaymentRequiredWithMessage

success boolean

Always false on error responses.

Sample: false

payload object

Context about the error, if any.

payload.code string

A translation key for the given message.

Sample: "example"

payload.message string object

The translated version of the message.

Click on "Example" to get its translated value.

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": {
        "code": "example",
        "message": "This is a translation sample"
    },
    "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.