Skip to main content

​
Overview

Tenants represent individual organizations or companies in the multi-tenant SaaS platform. Each tenant has its own isolated database schema, subscription plan, and user assignments. The tenant architecture uses PostgreSQL schema-per-tenant isolation to ensure complete data separation between organizations.

​
Schema Isolation

Each tenant is provisioned with:
  • A unique PostgreSQL schema (e.g., tenant_123)
  • Isolated tables for all operational data (invoices, products, users, etc.)
  • Dedicated DTE (electronic tax document) configuration
  • Plan-based resource limits (users, documents, etc.)
The schema_name field determines which physical PostgreSQL schema the tenant’s data resides in, enabling complete data isolation while sharing the same database instance.

​
Create Tenant

Registers a new tenant organization in the SaaS platform. This endpoint provisions a new tenant with an exclusive database schema and migrates all operational tables into the tenant’s isolated environment.

​
Headers

​
Authorization
string
required
Bearer token for authenticated superuser

​
Body

​
name
string
required
Company or organization name
​
rut
string
required
Chilean tax identification number (RUT)
​
address
string
Physical address of the organization
​
commune
string
Commune (municipality) where the organization is located
​
city
string
City where the organization is located
​
giro
string
Business line or industry description
​
billing_day
integer
default:"1"
Day of the month for billing and invoicing (1-31)
​
economic_activities
array
List of ACTECO economic activity codes and details. Each activity should include:
  • code (string): ACTECO code
  • name (string): Activity description
  • category (string): Activity category (e.g., “1ra”)
  • taxable (boolean): Whether the activity is taxable

​
Response

​
id
integer
Unique tenant identifier
​
name
string
Tenant organization name
​
rut
string
Chilean tax identification number
​
schema_name
string
PostgreSQL schema name for this tenant (e.g., “tenant_123”)
​
is_active
boolean
Whether the tenant is currently active
​
plan_id
integer
Associated subscription plan ID
​
max_users_override
integer
Custom user limit override (null uses plan default)
​
plan_max_users
integer
Maximum users allowed based on plan or override
​
address
string
Physical address
​
commune
string
Commune/municipality
​
city
string
City
​
giro
string
Business line description
​
billing_day
integer
Day of month for billing (1-31)
​
economic_activities
array
Array of economic activity objects with code, name, category, and taxable fields
​
created_at
string
ISO 8601 timestamp of tenant creation
curl -X POST https://api.torn.cl/saas/tenants \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comercial Los Pinos Ltda",
    "rut": "76.123.456-7",
    "address": "Av. Libertador Bernardo O'\''Higgins 1234",
    "commune": "Santiago",
    "city": "Santiago",
    "giro": "Venta al por menor de productos alimenticios",
    "billing_day": 15,
    "economic_activities": [
      {
        "code": "471110",
        "name": "Venta al por menor en comercios no especializados",
        "category": "1ra",
        "taxable": true
      }
    ]
  }'

{
  "id": 42,
  "name": "Comercial Los Pinos Ltda",
  "rut": "76.123.456-7",
  "schema_name": "tenant_42",
  "is_active": true,
  "plan_id": 1,
  "max_users_override": null,
  "plan_max_users": 3,
  "address": "Av. Libertador Bernardo O'Higgins 1234",
  "commune": "Santiago",
  "city": "Santiago",
  "giro": "Venta al por menor de productos alimenticios",
  "billing_day": 15,
  "economic_activities": [
    {
      "code": "471110",
      "name": "Venta al por menor en comercios no especializados",
      "category": "1ra",
      "taxable": true
    }
  ],
  "created_at": "2026-03-08T14:30:00Z"
}

​
Error Responses

​
400 Bad Request
Returned when tenant creation fails due to validation errors or provisioning issues.
{
  "detail": "Error creando el inquilino: Schema name already exists"
}
​
403 Forbidden
Returned when the authenticated user is not a superuser.
{
  "detail": "Not authorized"
}

​
List Tenants

Retrieves a list of all tenant organizations. This endpoint is restricted to superusers only.

​
Headers

​
Authorization
string
required
Bearer token for authenticated superuser

​
Response

Returns an array of tenant objects with the same structure as the Create Tenant response. 
curl -X GET https://api.torn.cl/saas/tenants \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": 42,
    "name": "Comercial Los Pinos Ltda",
    "rut": "76.123.456-7",
    "schema_name": "tenant_42",
    "is_active": true,
    "plan_id": 1,
    "max_users_override": null,
    "plan_max_users": 3,
    "address": "Av. Libertador Bernardo O'Higgins 1234",
    "commune": "Santiago",
    "city": "Santiago",
    "giro": "Venta al por menor de productos alimenticios",
    "billing_day": 15,
    "economic_activities": [
      {
        "code": "471110",
        "name": "Venta al por menor en comercios no especializados",
        "category": "1ra",
        "taxable": true
      }
    ],
    "created_at": "2026-03-08T14:30:00Z"
  },
  {
    "id": 43,
    "name": "Ferretería El Constructor SA",
    "rut": "77.234.567-8",
    "schema_name": "tenant_43",
    "is_active": true,
    "plan_id": 2,
    "max_users_override": 10,
    "plan_max_users": 10,
    "address": "Calle Principal 567",
    "commune": "Providencia",
    "city": "Santiago",
    "giro": "Venta de artículos de ferretería",
    "billing_day": 1,
    "economic_activities": [],
    "created_at": "2026-03-07T10:15:00Z"
  }
]

​
Error Responses

​
403 Forbidden
Returned when the authenticated user is not a superuser.
{
  "detail": "Not authorized"
}

​
Update Tenant

Updates tenant information. When DTE-related fields (name, address, commune, city, giro, economic_activities) are updated, the changes are automatically synchronized to the tenant’s local database schema, updating the issuer information.

​
Headers

​
Authorization
string
required
Bearer token for authenticated superuser

​
Path Parameters

​
tenant_id
integer
required
The unique identifier of the tenant to update

​
Body

All fields are optional. Only include fields you want to update.
​
name
string
Updated company name
​
is_active
boolean
Whether the tenant should be active
​
max_users_override
integer
Custom user limit (overrides plan default)
​
address
string
Updated physical address
​
commune
string
Updated commune/municipality
​
city
string
Updated city
​
giro
string
Updated business line description
​
billing_day
integer
Updated billing day (1-31)
​
economic_activities
array
Updated list of economic activities

​
Response

Returns the updated tenant object with the same structure as the Create Tenant response. 
curl -X PATCH https://api.torn.cl/saas/tenants/42 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_users_override": 10,
    "address": "Nueva Dirección 999",
    "city": "Viña del Mar"
  }'

{
  "id": 42,
  "name": "Comercial Los Pinos Ltda",
  "rut": "76.123.456-7",
  "schema_name": "tenant_42",
  "is_active": true,
  "plan_id": 1,
  "max_users_override": 10,
  "plan_max_users": 10,
  "address": "Nueva Dirección 999",
  "commune": "Santiago",
  "city": "Viña del Mar",
  "giro": "Venta al por menor de productos alimenticios",
  "billing_day": 15,
  "economic_activities": [
    {
      "code": "471110",
      "name": "Venta al por menor en comercios no especializados",
      "category": "1ra",
      "taxable": true
    }
  ],
  "created_at": "2026-03-08T14:30:00Z"
}

​
Error Responses

​
403 Forbidden
Returned when the authenticated user is not a superuser.
{
  "detail": "Not authorized"
}
​
404 Not Found
Returned when the specified tenant does not exist.
{
  "detail": "Tenant not found"
}

​
Deactivate Tenant

Performs a soft delete on a tenant by setting is_active to false. The tenant’s data and schema are preserved but the organization is marked as inactive.

​
Headers

​
Authorization
string
required
Bearer token for authenticated superuser

​
Path Parameters

​
tenant_id
integer
required
The unique identifier of the tenant to deactivate

​
Response

Returns HTTP 204 No Content on success. 
curl -X DELETE https://api.torn.cl/saas/tenants/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Error Responses

​
403 Forbidden
Returned when the authenticated user is not a superuser.
{
  "detail": "Not authorized"
}
​
404 Not Found
Returned when the specified tenant does not exist.
{
  "detail": "Tenant not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us