Client Management

The Client Management API gives you full control over your client tenants — create them, configure their limits, monitor their usage, and manage their lifecycle.

Base path: /api/v1/tenants

---

Tenant object

{
  "id": "ten_01HXABC123DEF",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "status": "active",
  "plan": "business",
  "agencyId": "agn_01HXABC...",
  "billingMode": "platform_billed",
  "usageLimits": {
    "monthlySpendLimitCents": 500000,
    "maxAgents": 20,
    "maxPhoneNumbers": 10,
    "maxConcurrentCalls": 20
  },
  "usageCurrentMonth": {
    "conversations": 842,
    "totalMinutes": 2841,
    "totalCostCents": 24388
  },
  "createdAt": "2025-01-15T10:00:00Z",
  "owner": {
    "id": "usr_01HXABC...",
    "email": "admin@acme.com",
    "name": "Jane Smith"
  }
}

---

Create a tenant

POST /api/v1/tenants

curl -X POST https://api.voisnap.ai/api/v1/tenants \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "business",
    "billingMode": "platform_billed",
    "owner": {
      "email": "admin@acme.com",
      "firstName": "Jane",
      "lastName": "Smith"
    },
    "usageLimits": {
      "monthlySpendLimitCents": 500000,
      "maxAgents": 20,
      "maxPhoneNumbers": 10,
      "maxConcurrentCalls": 20
    },
    "billingAlerts": {
      "alertThresholds": [50, 80, 100],
      "alertEmails": ["billing@youragency.com", "admin@acme.com"],
      "actionAt100": "notify_only"
    }
  }'

tenant = client.tenants.create(
    name="Acme Corp",
    slug="acme-corp",
    plan="business",
    billing_mode="platform_billed",
    owner={
        "email": "admin@acme.com",
        "first_name": "Jane",
        "last_name": "Smith",
    },
    usage_limits={
        "monthly_spend_limit_cents": 500000,
        "max_agents": 20,
        "max_phone_numbers": 10,
        "max_concurrent_calls": 20,
    }
)
print(f"Tenant created: {tenant.id}")
print(f"Owner invitation sent to: admin@acme.com")

const tenant = await client.tenants.create({
  name: 'Acme Corp',
  slug: 'acme-corp',
  plan: 'business',
  billingMode: 'platform_billed',
  owner: {
    email: 'admin@acme.com',
    firstName: 'Jane',
    lastName: 'Smith',
  },
  usageLimits: {
    monthlySpendLimitCents: 500000,
    maxAgents: 20,
    maxPhoneNumbers: 10,
    maxConcurrentCalls: 20,
  },
});

When a tenant is created, the owner receives an invitation email to set up their account and access the white-labeled portal.

---

List tenants

GET /api/v1/tenants

curl "https://api.voisnap.ai/api/v1/tenants?status=active&sortBy=name" \
  -H "Authorization: Bearer vsnp_live_..."

for tenant in client.tenants.list(status="active"):
    usage = tenant.usage_current_month
    print(f"{tenant.name}: {usage['conversations']} calls, ${usage['total_cost_cents']/100:.2f}")

---

Get a tenant

GET /api/v1/tenants/{tenantId}

---

Update a tenant

PATCH /api/v1/tenants/{tenantId}

curl -X PATCH https://api.voisnap.ai/api/v1/tenants/ten_01HXABC123DEF \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "usageLimits": {
      "monthlySpendLimitCents": 1000000,
      "maxAgents": 50
    }
  }'

---

Assign users to a tenant

As the agency, you can add users to any of your client tenants:

POST /api/v1/tenants/{tenantId}/users/invite

curl -X POST https://api.voisnap.ai/api/v1/tenants/ten_01HXABC123DEF/users/invite \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@acme.com",
    "firstName": "Bob",
    "lastName": "Dev",
    "role": "TenantUser"
  }'

---

View client analytics

GET /api/v1/tenants/{tenantId}/analytics

curl "https://api.voisnap.ai/api/v1/tenants/ten_01HXABC123DEF/analytics?dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "tenantId": "ten_01HXABC123DEF",
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "conversations": 1482,
  "totalMinutes": 4812,
  "totalCostUsd": 127.43,
  "agentCount": 4,
  "activeAgents": 3,
  "channelBreakdown": { "phone": 1240, "webrtc": 180, "webchat": 62 },
  "avgSentimentScore": 0.72
}

---

Cross-client analytics

Get a rolled-up view across all your clients:

GET /api/v1/agency/analytics

curl "https://api.voisnap.ai/api/v1/agency/analytics?dateFrom=2025-06-01&dateTo=2025-06-30" \
  -H "Authorization: Bearer vsnp_live_..."

Response:

{
  "period": { "from": "2025-06-01", "to": "2025-06-30" },
  "totalTenants": 12,
  "activeTenants": 11,
  "totalConversations": 18420,
  "totalCostUsd": 1842.10,
  "topTenants": [
    { "id": "ten_01HXABC", "name": "Acme Corp", "conversations": 4812, "revenue": 2490 },
    { "id": "ten_01HXDEF", "name": "Beta Inc", "conversations": 3240, "revenue": 1850 }
  ]
}

---

Deactivate a tenant

Suspends the tenant — all agents deactivated, no new calls or API access. Data preserved.

POST /api/v1/tenants/{tenantId}/deactivate

curl -X POST https://api.voisnap.ai/api/v1/tenants/ten_01HXABC123DEF/deactivate \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Non-payment", "notifyOwner": true }'

---

Reactivate a tenant

POST /api/v1/tenants/{tenantId}/reactivate

---

Transfer a tenant

Transfer a client tenant to another agency account (e.g., if they want to switch agencies or become self-managed):

POST /api/v1/tenants/{tenantId}/transfer

curl -X POST https://api.voisnap.ai/api/v1/tenants/ten_01HXABC123DEF/transfer \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetAgencyId": "agn_01HXNEW...",
    "note": "Client requested to manage their own account"
  }'

The transfer requires acceptance by the target agency (or Voisnap support if transferring to self-managed). All data, agents, and phone numbers transfer intact.