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#

Field	Type	Description
`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#

Field	Type	Description
`{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#

Field	Type	Description
`{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 Customer 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
}

Workflow usage monitoring by customer#

The API provides endpoints that allow you to monitor which workflows have been used by a customer in a given time period. This includes workflows that were used in the given time period but have since been deleted. Workflows in use can be accessed on a monthly, weekly, daily, or hourly basis:

GET /reseller/customers/{customer_id}/usage/workflows/monthly?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/weekly?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/daily?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/hourly?start={start}&end={end} (see also the auto-generated API documentation)

Note: The above endpoints do not return the usage data itself, but rather a list of URL endpoint references that serve as entry points to access the corresponding detailed usage data per workflow. See below.

Parameters#

Field	Type	Description
`{customer_id}`	UUID	The identifier of the customer for which the used workflows are to be accessed.

Query Parameters#

Field	Type	Description
start	partial ISO-8601 datetime	Start of the requested range as partial ISO-8601 datetime must be provided as query parameter. Input format depends on the specific endpoint and can be found in the respective documentation. Additional precision is discarded. Serves as an inclusive lower bound for the returned data points.
end (optional)	partial ISO-8601 datetime	End of the requested range as partial ISO-8601 datetime can optionally be provided as query parameter. Input format depends on the specific endpoint and can be found in the respective documentation. Additional precision is discarded. Serves as an inclusive upper bound for the returned data points.

Response#

If successful, returns an application/json response body containing a list of URL references pre-filled with the corresponding parameters, which can then be used to further retrieve detailed usage counts by workflow. See the next section for how to access the respective endpoint.

Example

  [
      {
        "workflow_id": "6a4be78c-8c4e-4c1e-83fe-5b8fed0ae34c",
        "usage_url": "/reseller/customers/d04270a6-6316-4d4b-b2c5-bff0ff515908/usage/workflows/workflow_id/6a4be78c-8c4e-4c1e-83fe-5b8fed0ae34c/monthly?start=2023-01&end=2023-12",
      },
      {
        "workflow_id": "b6a9d5cc-56f8-4bb5-8816-00b2c4c7c6dc",
        "usage_url": "/reseller/customers/d04270a6-6316-4d4b-b2c5-bff0ff515908/usage/workflows/workflow_id/b6a9d5cc-56f8-4bb5-8816-00b2c4c7c6dc/monthly?start=2023-01&end=2023-12",
      }
  ]

Workflow usage monitoring by customer and by workflow#

The API provides endpoints to access a customer's workflow usage data for a single workflow in a given time period. This includes usage data for workflows that were used in the given time period but have since been deleted. Basic usage is measured by credits processed, but by querying with &extended=true the endpoints will also return the number of documents processed, the number of pages processed, and the average processing time per page. Usage data can be retrieved in aggregated form, either on a monthly, weekly, daily or hourly basis:

GET /reseller/customers/{customer_id}/usage/workflows/{workflow_id}/monthly?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/{workflow_id}/weekly?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/{workflow_id}/daily?start={start}&end={end} (see also the auto-generated API documentation)

GET /reseller/customers/{customer_id}/usage/workflows/{workflow_id}/hourly?start={start}&end={end} (see also the auto-generated API documentation)

Parameters#

Field	Type	Description
`{customer_id}`	UUID	The identifier of the customer for which the usage data shall be accessed.
`{workflow_id}`	UUID	The identifier of the workflow for which the usage data shall be accessed.

Query Parameters#

Field	Type	Description
start	partial ISO-8601 datetime	Start of the requested range as partial ISO-8601 datetime must be provided as query parameter. Input format depends on the specific endpoint and can be found in the respective documentation. Additional precision is discarded. Serves as an inclusive lower bound for the returned data points.
end (optional)	partial ISO-8601 datetime	End of the requested range as partial ISO-8601 datetime can optionally be provided as query parameter. Input format depends on the specific endpoint and can be found in the respective documentation. Additional precision is discarded. Serves as an inclusive upper bound for the returned data points.
extended (optional)	Boolean	If this flag is set to `true`, additional indicators (num_documents, num_pages, average_time_per_page) will be aggregated for each period.

Response#

If successful, returns an application/json response body containing a list of usage data for the given customer and workflow.

Example

  [
      {
        "date": "2023-01",
        "processed_credits": 21,
      },
      {
        "date": "2023-02",
        "processed_credits": 102,
      },
      {
        "date": "2023-03",
        "processed_credits": 54,
      },
     ...
  ]

Create#

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

Parameters#

Field	Type	Description
`{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:

Field	Type	Description
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#

Field	Type	Description
`{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:

Field	Type	Description
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#

Field	Type	Description
`{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#

Field	Type	Description
`{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"
  }

Reseller Endpoints#

Customer-related Endpoints#

Create#

Request Body#

Response#

Modify#

Parameters#

Request Body#

Response#

Delete#

Parameters#

Response#

List#

Response#

Workflow usage monitoring by customer#

Parameters#

Query Parameters#

Response#

Workflow usage monitoring by customer and by workflow#

Parameters#

Query Parameters#

Response#

User-related Endpoints#

Create#

Parameters#

Request Body#

Response#

Update#

Parameters#

Request Body#

Response#

Delete#

Parameters#

Request Body#

Response#

List#

Parameters#

Request Body#

Response#