tenants

Create Tenant

Create a new tenant (organization/customer) - Usually auto-created during signup.

⚠️ NOTE: For most users, tenants are AUTO-CREATED during signup!

When to use this endpoint:

Platform Admins: Manually create organizations for customers
Recovery: If auto-creation failed during signup
Migration: Importing existing organizations into the platform
Advanced: Creating additional sub-organizations

For Regular Users (BUSINESS role):

Your tenant is automatically created when you sign up via POST /auth/signup
You don’t need to call this endpoint
Your tenant_id = your owner_id (automatically linked)

What it does:

Creates a new tenant account with unique ID (uses current_user.owner_id)
Sets up billing plan and usage limits
Configures SIP capabilities (if enabled)
Establishes compliance settings (HIPAA, PCI)
Encrypts sensitive credentials (SIP passwords)

Key Configuration:

name: Organization name
billing_plan: Subscription tier (starter/business/enterprise)
max_concurrent_calls: Call capacity limit (1-1000)
monthly_call_limit: Monthly usage cap
sip_enabled: Enable phone number integration
recording_enabled: Call recording capability
analytics_enabled: Analytics dashboard access

User Flow Clarification:

Sign up → POST /auth/signup (role=BUSINESS) → Tenant auto-created ✅
Login → POST /auth/token → Get access token
Create agents → POST /agents → Start building

❌ You do NOT need to manually create tenant after signup!

POST

tenants

Create Tenant

curl --request POST \
  --url https://api.example.com/tenants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "billing_plan": "<string>",
  "sip_enabled": false,
  "recording_enabled": true,
  "analytics_enabled": true,
  "max_concurrent_calls": 10,
  "monthly_call_limit": 1000,
  "sip_domain": "<string>",
  "sip_username": "<string>",
  "sip_password": "<string>"
}
'

{
  "name": "<string>",
  "billing_plan": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "monthly_usage_cents": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "sip_enabled": false,
  "recording_enabled": true,
  "analytics_enabled": true,
  "max_concurrent_calls": 10,
  "monthly_call_limit": 1000,
  "meta_data": {},
  "sip_domain": "<string>",
  "sip_username": "<string>",
  "hipaa_enabled": false,
  "pci_enabled": false,
  "recording_format": "mp4",
  "retention_days": 90,
  "data_encryption_enabled": true,
  "webhook_url": "<string>",
  "webhook_timeout_seconds": 20
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Tenant creation model.

name

string

required

Required string length: 1 - 255

billing_plan

string

required

Required string length: 1 - 100

sip_enabled

boolean

default:false

recording_enabled

boolean

default:true

analytics_enabled

boolean

default:true

max_concurrent_calls

integer

default:10

Required range: 1 <= x <= 1000

monthly_call_limit

integer

default:1000

Required range: x >= 0

sip_domain

string | null

sip_username

string | null

sip_password

string | null

Response

Successful Response

Tenant response model.

name

string

required

Required string length: 1 - 255

billing_plan

string

required

Required string length: 1 - 100

string<uuid>

required

status

string

required

monthly_usage_cents

integer

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

sip_enabled

boolean

default:false

recording_enabled

boolean

default:true

analytics_enabled

boolean

default:true

max_concurrent_calls

integer

default:10

Required range: 1 <= x <= 1000

monthly_call_limit

integer

default:1000

Required range: x >= 0

meta_data

Meta Data · object

sip_domain

string | null

sip_username

string | null

hipaa_enabled

boolean

default:false

pci_enabled

boolean

default:false

recording_format

string

default:mp4

retention_days

integer

default:90

data_encryption_enabled

boolean

default:true

webhook_url

string | null

webhook_timeout_seconds

integer

default:20

Get TenantGet detailed information about a specific tenant. **Purpose:** Retrieve complete tenant profile and configuration **What it does:** - Returns complete tenant profile - Shows billing, usage, and configuration details - Displays SIP settings and compliance status - Shows webhook configuration for integrations **Response Includes:** - Organization details (name, status, created_at) - Billing plan and usage limits - Feature flags (sip_enabled, recording_enabled, analytics_enabled) - Compliance settings (hipaa_enabled, pci_enabled) - Recording format and retention policy (retention_days) - Webhook URL for event notifications - Monthly usage tracking (monthly_usage_cents) - Creation and update timestamps **Use Cases:** - Viewing customer account details - Auditing tenant configuration - Billing and usage review - Support and troubleshooting

Create Tenant

curl --request POST \
  --url https://api.example.com/tenants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "billing_plan": "<string>",
  "sip_enabled": false,
  "recording_enabled": true,
  "analytics_enabled": true,
  "max_concurrent_calls": 10,
  "monthly_call_limit": 1000,
  "sip_domain": "<string>",
  "sip_username": "<string>",
  "sip_password": "<string>"
}
'

{
  "name": "<string>",
  "billing_plan": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "monthly_usage_cents": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "sip_enabled": false,
  "recording_enabled": true,
  "analytics_enabled": true,
  "max_concurrent_calls": 10,
  "monthly_call_limit": 1000,
  "meta_data": {},
  "sip_domain": "<string>",
  "sip_username": "<string>",
  "hipaa_enabled": false,
  "pci_enabled": false,
  "recording_format": "mp4",
  "retention_days": 90,
  "data_encryption_enabled": true,
  "webhook_url": "<string>",
  "webhook_timeout_seconds": 20
}

Documentation Index

Authorizations

Body

Response