Skip to content

Reseller Endpoints#

If you are a reseller, you can use the following routes to manage your customers and users within those customers.

Create#

Customers can be created via the POST /reseller/customers endpoint. See also the auto-generated API documentation.

Request Body#

FieldTypeDescription
name string Should be a unique and speakable name to later on reliably identify the customer.
organizational_info object Holds meta-data about the organization related to this customer, e.g. addresses or additional data-protection flags. For the exact shape of this object, please refer to the Schema definition in the auto-generated API specification.
use_technical_interface bool Deprecated, has no effect anymore. If set to `true`, all Users within this Customer will be presented the extended technical interface after login on platform.natif.ai. This is recommended only if Users from this customer will need features that the new Interface does not (yet) provide. By default (recommended), they will be shown the new streamlined web experience. Can be changed afterwards.

Response#

On success, returns a JSON object containing the single key customer_id, defining the unique identifier for the newly created customer. This identifier is needed for any other related action for this customer, e.g. managing users within it, modifying settings, retrieving usage metrics, etc.

Modify#

Customers with a known customer_id can be modified via the PUT /reseller/customers/{customer_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer.

Request Body#

The submitted application/json body parameters are similar to the ones provided at time of initial customer creation. Values that are not included into the submitted JSON body will not be updated and stay as-is, i.e. the data update can be partial.

Response#

On success, returns an empty response.

Delete#

Customers with a known customer_id can be deleted via the DELETE /reseller/customers/{customer_id} endpoint. See also the auto-generated API documentation.

Warning

Deleting the customer also deletes all remaining user accounts, documents, and self-created workflows within this customer! Please be careful!

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer.

Response#

On success, returns an empty response.

List#

With the GET /reseller/customers endpoint, you can list all existing customers from your own realm. See also the auto-generated API documentation.

Response#

On success, returns an application/json response body containing a list of User objects in the following form:

Customer object 
{
  "name": "string",
  "organizational_info": {
    "company_name": "string",
    "industry": "string",
    "number_of_employees": 0,
    "sector": "string",
    "paragraph_203_StGB_applies": true,
    "address": {
      "address_line_1": "",
      "address_line_2": "",
      "city": "string",
      "zip_code": "0",
      "country": "AD"
    },
    "additional_sensitive_personal_data_attributes": "string"
  },
  "use_technical_interface": true
}

Create#

User accounts can be created via the POST /reseller/customers/{customer_id}/users endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user should be created in.

Request Body#

The request to this endpoint needs to include an application/json encoded object containing the following fields:

FieldTypeDescription
username string >email< The email for the new user. If no initial password is provided, instructions on how to complete the account setup are sent to this address.
password (optional) string The default is to not provide a password. In this case the customer is sent an email with a link to verify the email address and set the password. If a password is provided, it is assumed that the email is verified and no further communication is sent to the customer. The password must be at least 12 characters long and must contain:
  • a minimum of 1 lower case letter [a-z] and
  • a minimum of 1 upper case letter [A-Z] and
  • a minimum of 1 numeric character [0-9] and
  • a minimum of 1 special character: 
    ~!@#$%^&*()-_+={}[]|;:<>,./?
role One of "manager" | "user" The role that will be assigned to this user and dictate the overall permissions the user will have within its customer.
first_name (optional) string The first name of the user.
last_name (optional) string The last name of the user.
job_title (optional) string The job title of the user
communication_language (optional) string The prefered communication language. Possible values are: en, de, ja, fr, es.
phone (optional) string Phone number of the user.

Response#

On success, returns a JSON object containing the single key user_id, defining the unique identifier for the newly created user. This identifier is needed for any other related action for this user, e.g. updating or deleting it, etc.

Update#

User accounts can be modified via the PUT /reseller/customers/{customer_id}/users/{user_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user is located in.
{user_id} UUID The identifier for the user that is to be modified.

Request Body#

The request to this endpoint needs to include an application/json encoded object containing the following fields:

FieldTypeDescription
first_name (optional) string The first name of the user.
last_name (optional) string The last name of the user.
job_title (optional) string The job title of the user

Fields that are not provided as part of the body or sent with a null value will not be updated and remain unmodified.

Response#

On success, returns an empty HTTP Response

Delete#

User accounts can be deleted via the DELETE /reseller/customers/{customer_id}/users/{user_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user should be deleted from.
{user_id} UUID The identifier for the user that is to be deleted.

Request Body#

None

Response#

On success, returns an empty HTTP Response

List#

User accounts within a customer can be listed with the GET /reseller/customers/{customer_id}/users endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer whose users should be returned.

Request Body#

None

Response#

On success, returns an application/json response body containing a list of User objects in the following form:

User object 
  {
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
    "username": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "job_title": "Engineer",
    "role": "user"
  }