[Public Customer] Create a customer.

Create a customer specifying its external_id, and allowing specific templates. Creating an already existing customer will return a 409 error.

POST

https://api.staging.wetransform.com/customer

Request Payload

Request

CustomerPublicCustomerRequest

Property / Description Constraints

template_handles

array

An array of template Handles that the customer can use.

Not Blank

Is Granted
attribute	TEMPLATE_MANAGE
entity class	template
identifier	handle

Unique

external_id ^*

string

Customer ID on receiver's side.

This customer ID will be used when signing requests while connecting a customer through the Embed API.

Sample value: "1234"

Length
max	70

name ^*

string

Customer's name

Sample value: "Michael Jackson"

Length
max	70

email ^*

string

Customer's email.

Useful if WeTransform is used in no-code mode, as customer will need to authenticate through a code sent by email.

Sample value: "mickael@jackson.com"

Email

Length
max	70

language ^*

string

The customer's preferred language.

Possible values: fr, en

Sample value: "fr"

Enum Value
enum type	language
deniedValues	[]

user_metadata

array

Customer-specific metadata.

Valid

user_metadata[].name

string

Sample value: "type"

Not Blank

Length
max	32
min	1

user_metadata[].value ^*

string

Sample value: "human_resources"

Length
max	4096
min	0

Properties suffixed with * are nullable.

Example Copy

{
    "template_handles": [
        "furniture",
        "leaves"
    ],
    "external_id": "1234",
    "name": "Michael Jackson",
    "email": "mickael@jackson.com",
    "language": "fr",
    "user_metadata": [
        {
            "name": "type",
            "value": "human_resources"
        },
        {
            "name": "department",
            "value": "accounting"
        }
    ]
}

Responses

200 OK

Response 200

ResponseSuccess CustomerPublicCustomerResponse

Property / Description
success boolean
Always `true` on successful responses. Sample value: `true`
payload object
Payload of the requested resource.
payload.customer_id ^* string
Customer ID (on WeTransform side)
payload.templates array

payload.templates[].template_handle ^* string
The template handle. Sample value: `"furniture"`
payload.templates[].user_metadata array
The template metadata.
payload.templates[].user_metadata[].name string
Sample value: `"internal_code"`
payload.templates[].user_metadata[].value ^* string
Sample value: `"TMPLT_001"`
payload.external_id ^* string
Customer ID on receiver's side. This customer ID will be used when signing requests while connecting a customer through the Embed API. Sample value: `"1234"`
payload.name ^* string
Customer's name Sample value: `"Michael Jackson"`
payload.email ^* string
Customer's email. Useful if WeTransform is used in no-code mode, as customer will need to authenticate through a code sent by email. Sample value: `"mickael@jackson.com"`
payload.language ^* string
The customer's preferred language. Possible values: `fr`, `en` Sample value: `"fr"`
payload.user_metadata array
Customer-specific metadata.
payload.user_metadata[].name string
Sample value: `"type"`
payload.user_metadata[].value ^* string
Sample value: `"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 value: `"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 value: `"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
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.

Example Copy

{
    "success": true,
    "payload": {
        "customer_id": null,
        "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": "mickael@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
    },
    "debug": []
}

A product CTA if user reached out his/her number of customers limit

Response 402

ResponseError HttpPaymentRequired

Property / Description
success boolean
Always `false` on error responses. Sample value: `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 value: `"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 value: `"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
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.

Example Copy

{
    "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
    },
    "debug": []
}

A customer already exists with the same external ID or email

Response 418

ResponseError ExceptionCustomerAlreadyExists

Property / Description
success boolean
Always `false` on error responses. Sample value: `false`
payload object
Context about the error, if any.
payload.code string
A translation key for the given message. Sample value: `"violations.customer.id_or_email_exist"`
payload.message string
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 value: `"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 value: `"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
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.

Example Copy

{
    "success": false,
    "payload": {
        "code": "violations.customer.id_or_email_exist",
        "message": "A customer already exists with either that ID or email."
    },
    "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
    },
    "debug": []
}

Bad request.

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

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.

Property / Description
success boolean
Always `false` on error responses. Sample value: `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 value: `"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 value: `"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
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.

Example Copy

{
    "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
    },
    "debug": []
}

Authentication required.

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

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.

Property / Description
success boolean
Always `false` on error responses. Sample value: `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 value: `"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 value: `"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
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.

Example Copy

{
    "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
    },
    "debug": []
}

Access denied.

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

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.

Property / Description
success boolean
Always `false` on error responses. Sample value: `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 value: `"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 value: `"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
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.

Example Copy

{
    "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
    },
    "debug": []
}

Payload contains invalid values.

Response 409 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).

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

Property / Description
success boolean
Always `false` on error responses. Sample value: `false`
payload object
Context about the error, if any.
payload.error object

payload.error.code string
A translation key for the given message. Sample value: `"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 value: `"title"`
payload.violations[].invalid_value ^*
The invalid value. Sample value: `""`
payload.violations[].message string
An error message describing the violation. Sample value: `"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 value: `"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 value: `"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
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.

Example Copy

{
    "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
    },
    "debug": []
}

Interactive Console

Please login in order to access the console.

Back to API Reference