API documentation

[Column] Create a column.

Create a new column in the given template. Constraints (validation functions applied on the column values) are managed independently via the public constraint endpoints.

POST https://api.wetransform.com/template/{templateHandle}/column

URL Parameters

Parameter	Description
`{templateHandle}`	The handle of the template the column should be created in

Request Payload

Request

ColumnPublicColumnRequest

Request facade for creating or updating a template column through the public API.

Use this facade to define the column position, name, type, importance, uniqueness, conditions, and metadata. Constraints (validation functions applied on the column values) are managed independently through the public constraint endpoints.

position ^* integer

The column position in the target file.

If not provided, will be calculated automatically.

Sample: 3

number

technical_name ^* string

The column technical name, as it will be rendered in the target file.

Sample: "age"

length

pretty_name ^* string

The column pretty name, as it will be rendered on the WeTransform interfaces.

Sample: "Age"

length

description ^* string

The column description.

It is not mandatory, but can be helpful to give more details about what should be inserted in the column.

Sample: "Employee age"

length

type ^* object

The column type.

It will be used to automate a few transformations, such as convert date or number formats.

Only one configuration object needs to be provided.

not null Create valid allowed form builder type

type.type string

The type of the expected answer.

This will be useful to render to the customer the right field based on what we (or receiver) expect.

Possible values: BOOLEAN, TEXT, NUMBER, DATE, CHOICE, VALUE, COLUMN, URL, EMAIL, IMAGE, JSON, DATE_FORMAT

Sample: "NUMBER"

not null enum value

type.boolean_data_type ^* object

valid

type.text_data_type ^* object

valid

type.number_data_type ^* object

valid

type.number_data_type.decimals ^* integer

The number of decimals at which number should be rounded.

Sample: 0

number

type.number_data_type.separator_decimals ^* string

The decimals separator (a comma, a dot...)

Sample: ""

type.number_data_type.separator_thousands ^* string

The thousand separator (a space, a comma...)

Sample: ""

type.number_data_type.trailing_zeros ^* boolean

Whether trailing zeros should be added to match the specified number of decimals.

Sample: false

type.date_data_type ^* object

valid

type.choice_data_type ^* object

valid

type.value_data_type ^* object

valid

type.column_data_type ^* object

valid

type.url_data_type ^* object

valid

type.email_data_type ^* object

valid

type.image_data_type ^* object

valid

type.json_data_type ^* object

valid

type.date_format_data_type ^* object

valid

uniqueness ^* boolean

Whether values in the same column should be distinct.

Sample: false

importance ^* string

The column importance.

A file basically can't be processed by the receiver if its mandatory information are not completely provided.

Possible values: required, conditional, optional

Sample: "required"

enum value

matchable_with_ai ^* boolean

Whether the column can be automatically matched with AI when creating a new transformation.

Sample: true

hidden ^* boolean

Whether the column should be hidden on the sender side interfaces.

Sample: false

user_metadata ^* array

User metadata associated to the column.

valid unique property

user_metadata[].name string

Sample: "internal_code"

not blank length

user_metadata[].value ^* string

Sample: "TMPLT_COLUMN_001"

length

conditions ^* string

Conditions under which the column constraints apply, written as a DSL string.

Each condition is made of four parts joined by slashes:

[chaining]/[left]/[operator]/[right]

chaining: how the condition combines with the others. One of: AND, OR. The first chaining may be omitted; in that case AND is implied.
left: a reference to a column. Use #(target_column) for a target column, %(source_column) for a source column, or *(custom_field) for a custom field.
operator: the comparison operator. One of: CONTAINS, CONTAINED_IN, NOT_CONTAINS, NOT_CONTAINED_IN, DUPLICATED, UNIQUE, TAG_MATCH, TAG_NOT_MATCH, BEGIN_WITH, NOT_BEGIN_WITH, END_WITH, NOT_END_WITH, EQUALS, NOT_EQUALS, GREATER_EQUALS, LOWER_EQUALS, GREATER, LOWER, IS_EMPTY, IS_NOT_EMPTY, LENGTH_EQUALS, LENGTH_NOT_EQUALS, LENGTH_GREATER, LENGTH_LOWER, MATCH, NOT_MATCH, REGEX, NOT_REGEX, DATE_BEFORE_EQUALS, DATE_AFTER_EQUALS, DATE_BEFORE, DATE_AFTER.
right: a literal value or another column reference (#(...), %(...), *(...)).

Multiple conditions can be chained on the same line with / or split across lines.

Examples:

AND/#(contract)/EQUALS/trainee
AND/#(age)/GREATER_THAN/18/OR/#(country)/EQUALS/FR
#(status)/EQUALS/active (no leading chaining, AND implied)

Available validation functions that can be referenced (e.g. by the receiving end):


begin_by	Checks if begins by a given text	`?begin_by(Value to check,Required prefix)`
is_between	Checks if a number is between A and B	`?is_between(Value to check,Low value,High value)`
is_number	Checks if is a valid standard number	`?is_number(Value to check)`
length_is_maximum	Checks if has a maximum length of	`?length_is_maximum(The value to check,The maximum length)`
length_is_minimum	Checks if has a minimum length of	`?length_is_minimum(The value to check,The minimum length)`
must_be_empty_if_other_empty	Must be empty if another value is empty	`?must_be_empty_if_other_empty(The value to check,The other column to check)`
must_be_empty_if_other_filled	Must be empty if another value is filled	`?must_be_empty_if_other_filled(The value to check,The other column to check)`
must_be_filled_if_other_empty	Must be filled if another value is empty	`?must_be_filled_if_other_empty(The value to check,The other column to check)`
must_be_filled_if_other_filled	Must be filled if another value is filled	`?must_be_filled_if_other_filled(The value to check,The other column to check)`
is_positive_number	Checks if a number is positive	`?is_positive_number(Value to check)`
is_upper	Checks if is in uppercase	`?is_upper(Text to check)`
matches_regex	Check if matches the regex	`?matches_regex(Text to validate,Regex pattern)`
is_filled_if_other_value_in	Must be filled when @other_column is in list @values_to_check	`?is_filled_if_other_value_in(The value to check,The other column to check,The list of values to check separated by a comma)`
is_valid_postal_code	Check if zip code is valid depending on country ISO2 code	`?is_valid_postal_code(Zip code to validate,Country code ISO 2 format)`
contains	Checks if the value contains a given text	`?contains(Value to check,Text that must be present)`
date_after_equals	Checks if a date is after or equal to another date	`?date_after_equals(Date to check,Minimum allowed date)`
date_after	Checks if a date is after another date	`?date_after(Date to check,Minimum allowed date)`
date_before_equals	Checks if a date is before or equal to another date	`?date_before_equals(Date to check,Maximum allowed date)`
date_before	Checks if a date is before another date	`?date_before(Date to check,Maximum allowed date)`
date_between	Checks if a date is between two values	`?date_between(Date to check,Minimum allowed date,Maximum allowed date)`
ends_by	Checks if the value ends with a given text	`?ends_by(Value to check,Required suffix)`
greater_or_equal_to	Checks if the value is greater than or equal to a limit	`?greater_or_equal_to(Value to check,Lower limit (included))`
greater_than	Checks if the value is strictly greater than a limit	`?greater_than(Value to check,Lower limit (excluded))`
is_lower	Checks if the value is lowercase	`?is_lower(Text to check)`
length_between	Checks if the length of the text is between a minimum and a maximum value (inclusive)	`?length_between(Value to check,Minimum length,Maximum length)`
length_equal_to	Checks if the length of the text is equal to the specified number	`?length_equal_to(Value to check,Expected length)`
less_or_equal_to	Checks if the value is less than or equal to a limit	`?less_or_equal_to(Value to check,Upper limit (included))`
less_than	Checks if the value is strictly less than a limit	`?less_than(Value to check,Upper limit (excluded))`
match_pattern	Checks if the value matches a wildcard pattern using * and ?	`?match_pattern(Value to check,Pattern to match (supports * and ?))`
not_begin_by	Checks if value does not begin with a given text	`?not_begin_by(Value to check,Forbidden prefix)`
not_contains	Checks if the value does not contain a given text	`?not_contains(Value to check,Text that must not be present)`
not_ends_by	Checks if the value does not end with a given text	`?not_ends_by(Value to check,Forbidden suffix)`
is_date_position	Check if date is in the future or in the past	`?is_date_position(Date to check,PAST or FUTURE)`
no_line_breaks	Checks that the content does not contain any carriage returns or newlines	`?no_line_breaks(Value to check)`
no_html_tags	Ensures the value contains no HTML tags except those explicitly allowed	`?no_html_tags(Value to check,Allowed tags (e.g. b/p/i))`
json_contains	Checks whether a JSON document contains a non-empty value at a given path	`?json_contains(JSON payload in which the value will be searched,Path of the value to check, starting with € at the root)`
json_array_length_equals	Checks if a JSON array has exactly the expected number of items	`?json_array_length_equals(JSON payload containing the array,Expected number of items in the array,Path to the array to check, starting with € at the root (optional))`
equal_to	Checks if a value is exactly equal to another	`?equal_to(Value to check,Expected value)`
is_unique_key	Combination of values must be unique across the dataset	`?is_unique_key(Column,First key column,Second key column,Third key column,Fourth key column,Fifth key column)`
check_ean	Checks that the value is exactly 13 digits with a valid EAN-13 (GS1 modulo-10) check digit	`?check_ean(Value to check)`
is_working_hour	Checks whether the server's current hour is within [start..end] (24h, 0-23). When start > end, the range is overnight.	`?is_working_hour(Column to check (ignored — time-of-day predicate),Start hour, 0-23,End hour, 0-23 (inclusive))`

Sample: "AND\/#(contract)\/EQUALS\/trainee"

valid conditions

Properties suffixed with * are nullable.

{
    "position": 3,
    "technical_name": "age",
    "pretty_name": "Age",
    "description": "Employee age",
    "type": {
        "type": "NUMBER",
        "boolean_data_type": null,
        "text_data_type": null,
        "number_data_type": {
            "decimals": 0,
            "separator_decimals": "",
            "separator_thousands": "",
            "trailing_zeros": false
        },
        "date_data_type": null,
        "choice_data_type": null,
        "value_data_type": null,
        "column_data_type": null,
        "url_data_type": null,
        "email_data_type": null,
        "image_data_type": null,
        "json_data_type": null,
        "date_format_data_type": null
    },
    "uniqueness": false,
    "importance": "required",
    "matchable_with_ai": true,
    "hidden": false,
    "user_metadata": [
        {
            "name": "internal_code",
            "value": "TMPLT_COLUMN_001"
        }
    ],
    "conditions": "AND\/#(contract)\/EQUALS\/trainee"
}

Copy

Responses

Response 200 The created column on success

ResponseSuccess ColumnPublicColumnResponse

Response facade for a template column returned by the public API.

Mirrors {@see \PublicColumnRequestFacade} on read, with the column UUID and the parent template handle added. The conditions field is re-serialised back to its DSL string form so round-tripping with the request facade is symmetric.

success boolean

Always true on successful responses.

Sample: true

payload object

Payload of the requested resource.

payload.column_id ^* string

The column UUID.

Sample: "ed01b8b4-7726-47ea-a11f-0a0a208b377f"

payload.template_handle ^* string

The handle of the template this column belongs to.

Sample: "employees"

payload.position ^* integer

The column position in the target file.

Sample: 3

payload.technical_name ^* string

The column technical name, as it will be rendered in the target file.

Sample: "age"

payload.pretty_name ^* string

The column pretty name, as it will be rendered on the WeTransform interfaces.

Sample: "Age"

payload.description ^* string

The column description.

Sample: "Employee age"

payload.type ^* object

The column type.

payload.type.type string

The type of the expected answer.

This will be useful to render to the customer the right field based on what we (or receiver) expect.

Possible values: BOOLEAN, TEXT, NUMBER, DATE, CHOICE, VALUE, COLUMN, URL, EMAIL, IMAGE, JSON, DATE_FORMAT

Sample: "NUMBER"

payload.type.boolean_data_type ^* object

payload.type.text_data_type ^* object

payload.type.number_data_type ^* object

payload.type.number_data_type.decimals ^* integer

The number of decimals at which number should be rounded.

Sample: 0

payload.type.number_data_type.separator_decimals ^* string

The decimals separator (a comma, a dot...)

Sample: ""

payload.type.number_data_type.separator_thousands ^* string

The thousand separator (a space, a comma...)

Sample: ""

payload.type.number_data_type.trailing_zeros ^* boolean

Whether trailing zeros should be added to match the specified number of decimals.

Sample: false

payload.type.date_data_type ^* object

payload.type.choice_data_type ^* object

payload.type.value_data_type ^* object

payload.type.column_data_type ^* object

payload.type.url_data_type ^* object

payload.type.email_data_type ^* object

payload.type.image_data_type ^* object

payload.type.json_data_type ^* object

payload.type.date_format_data_type ^* object

payload.uniqueness ^* boolean

Whether values in the same column should be distinct.

Sample: false

payload.importance ^* string

The column importance.

Sample: "required"

payload.matchable_with_ai ^* boolean

Whether the column can be automatically matched with AI.

Sample: true

payload.hidden ^* boolean

Whether the column is hidden on the sender side interfaces.

Sample: false

payload.user_metadata ^* array

User metadata associated to the column.

payload.user_metadata[].name string

Sample: "internal_code"

payload.user_metadata[].value ^* string

Sample: "TMPLT_COLUMN_001"

payload.conditions ^* string

Conditions associated to the column, serialised back to the DSL string format (see {@see PublicColumnRequestFacade::$conditions} for the format reference).

Sample: "AND\/#(contract)\/EQUALS\/trainee"

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": {
        "column_id": "ed01b8b4-7726-47ea-a11f-0a0a208b377f",
        "template_handle": "employees",
        "position": 3,
        "technical_name": "age",
        "pretty_name": "Age",
        "description": "Employee age",
        "type": {
            "type": "NUMBER",
            "boolean_data_type": null,
            "text_data_type": null,
            "number_data_type": {
                "decimals": 0,
                "separator_decimals": "",
                "separator_thousands": "",
                "trailing_zeros": false
            },
            "date_data_type": null,
            "choice_data_type": null,
            "value_data_type": null,
            "column_data_type": null,
            "url_data_type": null,
            "email_data_type": null,
            "image_data_type": null,
            "json_data_type": null,
            "date_format_data_type": null
        },
        "uniqueness": false,
        "importance": "required",
        "matchable_with_ai": true,
        "hidden": false,
        "user_metadata": [
            {
                "name": "internal_code",
                "value": "TMPLT_COLUMN_001"
            }
        ],
        "conditions": "AND\/#(contract)\/EQUALS\/trainee"
    },
    "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 A product CTA if the number of columns per template limit has been reached

ResponseError HttpPaymentRequired

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