WeTransform API documentation

Create a customer

Create a customer identified by an external_id, an email, or both (at least one is required), and optionally grant it access to templates with template_handles.

If a deleted customer has the same external ID or email, it is restored and updated instead of created: it keeps its original customer_id and counts against your plan's customer limit again. If an active customer already uses the external ID or email, the call fails with a 409. Returns 200 with the customer.

POST https://api.wetransform.com/customer
Request Payload
Request
CustomerPublicCustomerRequest
template_handles array

Handles of the templates this customer may use.

When sent, it replaces the customer's whole template list (send [] to revoke all). When omitted, the list is unchanged. Each handle must belong to a template you are allowed to manage.

required is granted unique
external_id string

Your own identifier for this customer, unique within your organisation.

It is the customer ID you sign when connecting a customer through Embed. Avoid / if you want to address the customer by it in URLs.

Sample: "1234"
max 70 characters
name string

Display name of the customer.
Sample: "Michael Jackson"
max 70 characters
email string

Customer's email, unique within your organisation.

Needed if the customer signs in to WeTransform themselves: they receive a login code at this address.

Sample: "michael@jackson.com"
email max 70 characters
language string

Language of the customer's interface and emails.

Possible values: fr, en.

Sample: "fr"
one of: fr, en
user_metadata array

Free-form name/value pairs stored on the customer, usable as list filters.

The list you send replaces the stored one.

user_metadata[].name string

Metadata key (max 32 characters).
Sample: "type"
required 1 to 32 characters
user_metadata[].value string

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

Sample: "human_resources"
0 to 4096 characters
Properties suffixed with * are nullable. 
{
    "template_handles": [
        "furniture",
        "leaves"
    ],
    "external_id": "1234",
    "name": "Michael Jackson",
    "email": "michael@jackson.com",
    "language": "fr",
    "user_metadata": [
        {
            "name": "type",
            "value": "human_resources"
        },
        {
            "name": "department",
            "value": "accounting"
        }
    ]
}
Copy
Responses
Response 200
ResponseSuccess CustomerPublicCustomerResponse
success boolean

Always true on successful responses.
Sample: true
payload object

Payload of the requested resource.
payload.customer_id string nullable

WeTransform ID (UUID) of the customer.
Sample: "4b3b4ba8-6c4e-4a4f-9b5e-2f1d8c7a9e10"
payload.templates array

Templates this customer can use.
payload.templates[].template_handle string nullable

Handle of a template this customer can send files to; pass it to the /template/{templateHandle} endpoints for details.

Sample: "furniture"
payload.templates[].user_metadata array

Key/value metadata you set on the template (its General settings), handy to group or filter the customer's templates on your side.

payload.templates[].user_metadata[].name string

Metadata key (max 32 characters).
Sample: "internal_code"
payload.templates[].user_metadata[].value string nullable

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

Sample: "TMPLT_001"
payload.external_id string nullable

Your own identifier for this customer, unique within your organisation.

It is the customer ID you sign when connecting a customer through Embed. Avoid / if you want to address the customer by it in URLs.

Sample: "1234"
payload.name string nullable

Display name of the customer.
Sample: "Michael Jackson"
payload.email string nullable

Customer's email, unique within your organisation.

Needed if the customer signs in to WeTransform themselves: they receive a login code at this address.

Sample: "michael@jackson.com"
payload.language string nullable

Language of the customer's interface and emails.

Possible values: fr, en.

Sample: "fr"
payload.user_metadata array

Free-form name/value pairs stored on the customer, usable as list filters.

The list you send replaces the stored one.

payload.user_metadata[].name string

Metadata key (max 32 characters).
Sample: "type"
payload.user_metadata[].value string nullable

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

Sample: "human_resources"
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": true,
    "payload": {
        "customer_id": "4b3b4ba8-6c4e-4a4f-9b5e-2f1d8c7a9e10",
        "templates": [
            {
                "template_handle": "furniture",
                "user_metadata": [
                    {
                        "name": "internal_code",
                        "value": "TMPLT_001"
                    },
                    {
                        "name": "uuid",
                        "value": "f4b3e2b5-4b2e-4d25-8f1b-2d1f2b3e4f5a"
                    }
                ]
            }
        ],
        "external_id": "1234",
        "name": "Michael Jackson",
        "email": "michael@jackson.com",
        "language": "fr",
        "user_metadata": [
            {
                "name": "type",
                "value": "human_resources"
            },
            {
                "name": "department",
                "value": "accounting"
            }
        ]
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 402 Your plan's customer limit is reached. `product` describes the upgrade needed.
ResponseError HttpPaymentRequired
success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 409 An active customer already uses this `external_id` or `email` (violation on that field), neither field was sent, or a template handle is not one you can manage.
ResponseError Violations
success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
payload.error object

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

payload.error.code string

A translation key for the given message.
Sample: "exception.violation"
payload.error.message string object

The translated version of the message.

Click on "Example" to get its translated value.

payload.violations array

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

payload.violations[].property_path string

Property having an invalid value.
Sample: "title"
payload.violations[].invalid_value nullable

The invalid value.
Sample: ""
payload.violations[].message string

An error message describing the violation.
Sample: "This value should not be blank"
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": {
        "error": {
            "code": "exception.violation",
            "message": "The provided payload contains property violations."
        },
        "violations": [
            {
                "property_path": "title",
                "invalid_value": "",
                "message": "This value should not be blank"
            },
            {
                "property_path": "price",
                "invalid_value": -5,
                "message": "The amount should be greater than 1"
            }
        ]
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 400 Bad request.
ResponseError HttpBadRequest

The client sent an unexpected request.

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

success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 401 Authentication required.
ResponseError HttpUnauthorized

User must be authenticated to access the resource.

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

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

success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 403 Access denied.
ResponseError HttpForbidden

User is well authenticated, but not authorized to access the resource.

It can happen if user is trying to use a feature that s/he didn't pay for, access someone else's resource, etc.

These issues are normally fixed by the frontend, which should render features and resources user has access to.

success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": [],
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Response 409 Payload contains invalid values.
ResponseError Violations Violation

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

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

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

success boolean

Always false on error responses.
Sample: false
payload object

Context about the error, if any.
payload.error object

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

payload.error.code string

A translation key for the given message.
Sample: "exception.violation"
payload.error.message string object

The translated version of the message.

Click on "Example" to get its translated value.

payload.violations array

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

payload.violations[].property_path string

Property having an invalid value.
Sample: "title"
payload.violations[].invalid_value nullable

The invalid value.
Sample: ""
payload.violations[].message string

An error message describing the violation.
Sample: "This value should not be blank"
product object nullable

A product needed.

Not null if user requires to buy a specific product (permission or limitation) in order to access a feature.

product.requirement string nullable

Whether the user requested a features s/he doesn't have access to, or the user needs greater limits. Possible values: permission, limitation

Sample: "permission"
product.permission object nullable

The required permission.

You will need to know which permission is needed in order to fill up search filters in the shop.

product.permission.description string nullable

A human-understandable name for the permission.
product.permission.name string

A technical permission name (ex: ORGANISATION_UPDATE_SETTINGS).

Possible values depend on the context, check the domain's metadata endpoint.

Sample: "X_SOURCE_FORMAT_XML"
product.limitation_type string nullable

The limitation that needs to be increased (ex: number of columns).
product.limitation_needed_value integer nullable

The needed resource quantity (if receiver uses 9 columns in a template, this value is 9).

product.limitation_current_value integer nullable

The current value of the limitation (if receiver is allowed to use 10 columns, this value is 10).

product.limitation_object object nullable

The limitation type in a readable format, for example, "lines per file".

product.ai_feature string nullable

The AI feature that could not run, when an AI feature is what hit the limitation (null for any other product). Possible values: rule_transformation, rule_template, rule_function, rule_constraint, column_constraints, normalizer, chat_db, doc_assistant, api_doc_assistant, autocorrect, autocorrect_fill, invoice_reader, column_match, value_match, power_populate_with_ai, power_extract_from_pdf, power_extract_from_spreadsheet, agent, column_enrichment, column_constraints_batch, agent_compression, agent_workflow_scaffold, agent_phase_fill, push_json_column_match, value_match_embedding, normalizer_debugger, power_extract_from_text, template_format_custom, power_describe_image, power_background_erase, hosted_image_view, value_match_context

product.message object nullable

What stopped, on what, and what it would take — translated and ready to display, with one wording per AI feature: "Matching the values of column «Couleur» with AI needs 12 AI credits, and 10 are left." Null whenever ai_feature is, and on the rare AI exposure that has no subject to name (the template collection's json_column_match_product covers no single template). Fall back to the generic call-to-action then.

product.is_cta boolean nullable

Whether a Call To Action should be displayed.

It may not be displayed if:

  • the limitation is on the membership role
  • the limitation is on the customer role
  • the user is a sender
debug array

Debug information.

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

Provided in development & admin modes only.

Properties suffixed with * are nullable. 
{
    "success": false,
    "payload": {
        "error": {
            "code": "exception.violation",
            "message": "The provided payload contains property violations."
        },
        "violations": [
            {
                "property_path": "title",
                "invalid_value": "",
                "message": "This value should not be blank"
            },
            {
                "property_path": "price",
                "invalid_value": -5,
                "message": "The amount should be greater than 1"
            }
        ]
    },
    "product": {
        "requirement": "permission",
        "permission": {
            "name": "X_SOURCE_FORMAT_XML",
            "description": "Can import XML files"
        },
        "limitation_type": null,
        "limitation_needed_value": null,
        "limitation_current_value": null,
        "limitation_object": null,
        "is_cta": false,
        "ai_feature": null,
        "message": null
    },
    "debug": []
}
Copy
Back to API Reference

Interactive Console

Please login in order to access the console.

© 2026