> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenant Configuration

Manage tenant configuration including notification channels, keywords, industries, risk matrix, website validation settings, billing, and account status. Tenant endpoints allow both self-service management (`/me` endpoints) and administrative management (`/{tenant_id}` endpoints).

## Overview

Tenant management endpoints provide:

* **Self-Service**: Tenants can manage their own configuration via `/me` endpoints
* **Administrative**: Admins can manage any tenant via `/{tenant_id}` endpoints
* **Configuration Areas**: Notifications, keywords, industries, risk matrix, website config, billing
* **Account Status**: Credits, subscription, usage tracking, watchlist seats

## Endpoints Overview

### Self-Service Endpoints (`/me`)

| Method  | Endpoint                                | Description                        |
| ------- | --------------------------------------- | ---------------------------------- |
| `GET`   | `/kyc/tenants/me`                       | Get current tenant's configuration |
| `PATCH` | `/kyc/tenants/me/notification-channels` | Update notification channels       |
| `GET`   | `/kyc/tenants/me/keywords`              | Get keywords                       |
| `PATCH` | `/kyc/tenants/me/keywords`              | Update keywords                    |
| `GET`   | `/kyc/tenants/me/industries`            | Get industries                     |
| `PATCH` | `/kyc/tenants/me/industries`            | Update industries                  |
| `GET`   | `/kyc/tenants/me/risk-matrix`           | Get risk matrix                    |
| `PATCH` | `/kyc/tenants/me/risk-matrix`           | Update risk matrix                 |
| `GET`   | `/kyc/tenants/me/website-config`        | Get website validation config      |
| `PATCH` | `/kyc/tenants/me/website-config`        | Update website validation config   |
| `GET`   | `/kyc/tenants/me/credits`               | Get available credits              |
| `GET`   | `/kyc/tenants/me/watchlist-seats`       | Get watchlist seats info           |
| `GET`   | `/kyc/tenants/me/account-status`        | Get full account status            |

### Administrative Endpoints (`/{tenant_id}`)

| Method   | Endpoint                                         | Description                             |
| -------- | ------------------------------------------------ | --------------------------------------- |
| `POST`   | `/kyc/tenants`                                   | Create new tenant (admin only)          |
| `GET`    | `/kyc/tenants/{tenant_id}`                       | Get tenant details                      |
| `PUT`    | `/kyc/tenants/{tenant_id}`                       | Update tenant (full update, admin only) |
| `DELETE` | `/kyc/tenants/{tenant_id}`                       | Delete tenant (admin only)              |
| `PATCH`  | `/kyc/tenants/{tenant_id}/notification-channels` | Update notification channels            |
| `PATCH`  | `/kyc/tenants/{tenant_id}/billing`               | Update billing configuration            |
| `GET`    | `/kyc/tenants/{tenant_id}/keywords`              | Get keywords                            |
| `PATCH`  | `/kyc/tenants/{tenant_id}/keywords`              | Update keywords                         |
| `GET`    | `/kyc/tenants/{tenant_id}/industries`            | Get industries                          |
| `PATCH`  | `/kyc/tenants/{tenant_id}/industries`            | Update industries                       |
| `GET`    | `/kyc/tenants/{tenant_id}/risk-matrix`           | Get risk matrix                         |
| `PATCH`  | `/kyc/tenants/{tenant_id}/risk-matrix`           | Update risk matrix                      |
| `GET`    | `/kyc/tenants/{tenant_id}/website-config`        | Get website validation config           |
| `PATCH`  | `/kyc/tenants/{tenant_id}/website-config`        | Update website validation config        |

## Authentication

* **Self-Service Endpoints**: Require appropriate read/update permissions
* **Administrative Endpoints**: Require `tenant:manage` permission
* Include your Bearer token in the Authorization header

***

## Get Current Tenant Configuration

Retrieve the current tenant's full configuration.

### Endpoint

```
GET /kyc/tenants/me
```

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.kyc.example.com/kyc/tenants/me",
      headers={"Authorization": f"Bearer {token}"}
  )
  tenant = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const tenant = await response.json();
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "tenant_id": "tenant123",
    "name": "My Company",
    "status": "active",
    "notification_config": {
      "webhook_url": "https://example.com/webhooks/kyc",
      "webhook_secret": "****************************a1b2",
      "notification_emails": ["alerts@example.com", "admin@example.com"],
      "slack_webhook_url": "https://hooks.slack.com/services/...",
      "batch_notifications_enabled": true
    },
    "keywords": [
      { "keyword": "gambling", "enabled": true },
      { "keyword": "crypto", "enabled": false }
    ],
    "industries": [
      { "id": 1, "name": "financial_services", "allowed": true, "flagged": false },
      { "id": 2, "name": "gambling", "allowed": false, "flagged": false },
      { "id": 3, "name": "cryptocurrency", "allowed": true, "flagged": true }
    ],
    "risk_matrix": {
      "ssl_weight": 0.15,
      "industry_weight": 0.20,
      "name_match_weight": 0.15,
      "sanction_weight": 0.15,
      "adverse_media_weight": 0.10,
      "social_links_weight": 0.10,
      "tranco_weight": 0.15
    },
    "website_config": {
      "adverse_media_enabled": true,
      "sanction_check_enabled": true,
      "social_links_validation_enabled": true,
      "tranco_rank_enabled": true
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  },
  "execution_context": {
    "timestamp": "2024-11-22T10:30:00Z"
  }
}
```

***

## Account Status

Get comprehensive account status including subscription, credits, usage, and watchlist seats.

### Endpoint

```
GET /kyc/tenants/me/account-status
```

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.kyc.example.com/kyc/tenants/me/account-status",
      headers={"Authorization": f"Bearer {token}"}
  )
  status = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/account-status', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const status = await response.json();
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "tenant_id": "tenant123",
    "tenant_name": "My Company",
    "status": "active",
    
    "subscription": {
      "status": "active",
      "product_id": "prod_enterprise",
      "current_period_start": "2024-11-01T00:00:00Z",
      "current_period_end": "2024-12-01T00:00:00Z",
      "limits": {
        "kyc_checks": 1000,
        "adverse_media_checks": 500,
        "crypto_checks": 200,
        "web_validations": 500
      },
      "usage": {
        "kyc_checks": 150,
        "adverse_media_checks": 45,
        "crypto_checks": 20,
        "web_validations": 75
      },
      "remaining": {
        "kyc_checks": 850,
        "adverse_media_checks": 455,
        "crypto_checks": 180,
        "web_validations": 425
      }
    },
    
    "free_tier": {
      "credits": {
        "kyc_checks": 10,
        "adverse_media_checks": 5,
        "crypto_checks": 5,
        "web_validations": 10
      }
    },
    
    "watchlist": {
      "available_seats": 100,
      "active_subjects": 45
    },
    
    "requires_payment": false,
    "can_do_screening": true
  }
}
```

### Response Fields

| Field                       | Type    | Description                                   |
| --------------------------- | ------- | --------------------------------------------- |
| `subscription.status`       | string  | `none`, `active`, `past_due`, `cancelled`     |
| `subscription.limits`       | object  | Monthly limits from subscription plan         |
| `subscription.usage`        | object  | Current month's usage                         |
| `subscription.remaining`    | object  | Remaining quota for current period            |
| `free_tier.credits`         | object  | One-time credits (not renewed monthly)        |
| `watchlist.available_seats` | integer | Total watchlist monitoring seats              |
| `watchlist.active_subjects` | integer | Currently monitored subjects                  |
| `requires_payment`          | boolean | True if no active subscription and no credits |
| `can_do_screening`          | boolean | True if can perform screenings                |

***

## Credits

Get available one-time credits (separate from subscription).

### Endpoint

```
GET /kyc/tenants/me/credits
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "credits": {
      "kyc_checks": 10,
      "adverse_media_checks": 5,
      "crypto_checks": 5,
      "web_validations": 10
    }
  }
}
```

***

## Watchlist Seats

Get watchlist monitoring seats information.

### Endpoint

```
GET /kyc/tenants/me/watchlist-seats
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "watchlist_seats": {
      "available_seats": 100,
      "active_subjects": 45,
      "remaining_seats": 55,
      "default_duration_days": 365
    }
  }
}
```

***

## Notification Channels

Update notification channels for alerts and webhooks.

### Endpoint

```
PATCH /kyc/tenants/me/notification-channels
```

### Request Body Parameters

<ParamFields>
  <ParamField name="webhook_url" type="string" description="Custom webhook URL for KYC event notifications" />

  <ParamField name="webhook_secret" type="string" description="Secret for webhook signature verification. Auto-generated if webhook_url is set without existing secret." />

  <ParamField name="notification_emails" type="array" description="List of email addresses for notifications" />

  <ParamField name="slack_webhook_url" type="string" description="Slack webhook URL for Slack notifications" />

  <ParamField name="batch_notifications_enabled" type="boolean" description="Enable/disable batch job notifications (default: true)" />
</ParamFields>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/notification-channels",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "webhook_url": "https://example.com/webhooks/kyc",
          "notification_emails": ["alerts@example.com", "admin@example.com"],
          "slack_webhook_url": "https://hooks.slack.com/services/T00/B00/XXX",
          "batch_notifications_enabled": True
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/notification-channels', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webhook_url: 'https://example.com/webhooks/kyc',
      notification_emails: ['alerts@example.com', 'admin@example.com'],
      slack_webhook_url: 'https://hooks.slack.com/services/T00/B00/XXX',
      batch_notifications_enabled: true
    })
  });
  ```
</CodeGroup>

<Note>
  When setting `webhook_url` for the first time, a `webhook_secret` is automatically generated if not provided. The secret follows the format `whsec_` + 64 hex characters.
</Note>

***

## Risk Matrix Configuration

Configure weights for web validation reliability score calculation.

### Get Risk Matrix

```
GET /kyc/tenants/me/risk-matrix
```

### Update Risk Matrix

```
PATCH /kyc/tenants/me/risk-matrix
```

### Request Body Parameters

<ParamFields>
  <ParamField name="risk_matrix" type="object" required description="Risk matrix configuration object">
    <ParamField name="ssl_weight" type="float" required description="Weight for SSL certificate score (0-1)" />

    <ParamField name="industry_weight" type="float" required description="Weight for industry classification score (0-1)" />

    <ParamField name="name_match_weight" type="float" description="Weight for declared name match score (0-1)" />

    <ParamField name="industry_match_weight" type="float" description="Weight for declared industry match score (0-1)" />

    <ParamField name="sanction_weight" type="float" description="Weight for sanction list check score (0-1)" />

    <ParamField name="adverse_media_weight" type="float" description="Weight for adverse media analysis score (0-1)" />

    <ParamField name="social_links_weight" type="float" description="Weight for social media links validation score (0-1)" />

    <ParamField name="tranco_weight" type="float" description="Weight for Tranco website ranking score (0-1)" />

    <ParamField name="terms_weight" type="float" description="Weight for terms & conditions policy score (0-1)" />

    <ParamField name="return_weight" type="float" description="Weight for return policy score (0-1)" />

    <ParamField name="refund_weight" type="float" description="Weight for refund policy score (0-1)" />

    <ParamField name="aml_weight" type="float" description="Weight for AML policy score (0-1)" />
  </ParamField>
</ParamFields>

<Warning>
  **Important**: The sum of all provided weights must equal exactly 1.0. Only include weights for checks you want to enable.
</Warning>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  # Basic risk matrix (SSL + Industry only)
  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/risk-matrix",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "risk_matrix": {
              "ssl_weight": 0.30,
              "industry_weight": 0.70
          }
      }
  )

  # Advanced risk matrix with all checks
  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/risk-matrix",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "risk_matrix": {
              "ssl_weight": 0.10,
              "industry_weight": 0.15,
              "name_match_weight": 0.10,
              "sanction_weight": 0.15,
              "adverse_media_weight": 0.15,
              "social_links_weight": 0.10,
              "tranco_weight": 0.10,
              "terms_weight": 0.05,
              "aml_weight": 0.10
          }
      }
  )
  ```

  ```javascript JavaScript theme={null}
  // Basic risk matrix
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/risk-matrix', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      risk_matrix: {
        ssl_weight: 0.30,
        industry_weight: 0.70
      }
    })
  });
  ```
</CodeGroup>

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "risk_matrix": {
      "ssl_weight": 0.10,
      "industry_weight": 0.15,
      "name_match_weight": 0.10,
      "sanction_weight": 0.15,
      "adverse_media_weight": 0.15,
      "social_links_weight": 0.10,
      "tranco_weight": 0.10,
      "terms_weight": 0.05,
      "aml_weight": 0.10
    }
  }
}
```

***

## Website Validation Config

Configure default settings for web validation checks.

### Get Website Config

```
GET /kyc/tenants/me/website-config
```

### Update Website Config

```
PATCH /kyc/tenants/me/website-config
```

### Request Body Parameters

<ParamFields>
  <ParamField name="website_config" type="object" required description="Website validation configuration">
    <ParamField name="adverse_media_enabled" type="boolean" description="Enable adverse media checks by default (default: false)" />

    <ParamField name="sanction_check_enabled" type="boolean" description="Enable sanction list checks by default (default: true)" />

    <ParamField name="social_links_validation_enabled" type="boolean" description="Enable social media links validation by default (default: true)" />

    <ParamField name="tranco_rank_enabled" type="boolean" description="Enable Tranco rank check by default (default: true)" />
  </ParamField>
</ParamFields>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/website-config",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "website_config": {
              "adverse_media_enabled": True,
              "sanction_check_enabled": True,
              "social_links_validation_enabled": True,
              "tranco_rank_enabled": True
          }
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/website-config', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      website_config: {
        adverse_media_enabled: true,
        sanction_check_enabled: true,
        social_links_validation_enabled: true,
        tranco_rank_enabled: true
      }
    })
  });
  ```
</CodeGroup>

<Tip>
  These settings define the **default** behavior for web validations. Individual requests can override these defaults using request parameters.
</Tip>

***

## Keywords Management

Keywords are used for website content blacklist filtering during web validation.

### Get Keywords

```
GET /kyc/tenants/me/keywords
```

### Update Keywords

```
PATCH /kyc/tenants/me/keywords
```

### Request Body Parameters

<ParamFields>
  <ParamField name="keywords" type="array" required description="Array of keyword objects (replaces entire list)">
    <ParamField name="keyword" type="string" required description="Keyword text to search for" />

    <ParamField name="enabled" type="boolean" required description="Whether the keyword is active" />
  </ParamField>
</ParamFields>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/keywords",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "keywords": [
              {"keyword": "gambling", "enabled": True},
              {"keyword": "casino", "enabled": True},
              {"keyword": "betting", "enabled": True},
              {"keyword": "crypto", "enabled": False}
          ]
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/keywords', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      keywords: [
        { keyword: 'gambling', enabled: true },
        { keyword: 'casino', enabled: true },
        { keyword: 'betting', enabled: true },
        { keyword: 'crypto', enabled: false }
      ]
    })
  });
  ```
</CodeGroup>

***

## Industries Management

Industries define which business categories are allowed or blocked for the tenant.

### Get Industries

```
GET /kyc/tenants/me/industries
```

### Update Industries

```
PATCH /kyc/tenants/me/industries
```

### Request Body Parameters

<ParamFields>
  <ParamField name="industries" type="array" required description="Array of industry objects (replaces entire list)">
    <ParamField name="id" type="integer" description="Tenant-scoped industry ID. Preserved when provided; auto-generated if omitted" />

    <ParamField name="name" type="string" required description="Industry identifier/name" />

    <ParamField name="allowed" type="boolean" required description="Whether the industry is allowed" />

    <ParamField name="flagged" type="boolean" description="Whether the industry requires extra scrutiny. Only meaningful when allowed=true. Flagged industries are permitted but trigger the on_flagged automation action during web validation. Default: false" />

    <ParamField name="description_en" type="string" description="English description" />

    <ParamField name="description_es" type="string" description="Spanish description" />

    <ParamField name="description_pt" type="string" description="Portuguese description" />

    <ParamField name="parent_id" type="integer" description="Parent industry ID for hierarchical classification" />
  </ParamField>
</ParamFields>

<Warning>
  **Keep IDs stable across updates.** This endpoint replaces the complete
  industry list. First read the current list with
  `GET /kyc/tenants/me/industries`, then include the `id` of every existing
  industry in the `PATCH`. If an item is sent without an `id`, LegalTalent
  assigns a new one. IDs belong to the tenant's catalog and must not be inferred
  from array order.
</Warning>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://api.kyc.example.com/kyc/tenants/me/industries",
      headers={
          "Authorization": f"Bearer {token}",
          "Content-Type": "application/json"
      },
      json={
          "industries": [
              {
                  "id": 101,
                  "name": "financial_services",
                  "allowed": True,
                  "description_en": "Financial Services"
              },
              {
                  "id": 102,
                  "name": "gambling",
                  "allowed": False,
                  "description_en": "Gambling & Betting"
              },
              {
                  "id": 103,
                  "name": "cryptocurrency",
                  "allowed": True,
                  "flagged": True,
                  "description_en": "Cryptocurrency & Blockchain"
              }
          ]
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants/me/industries', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      industries: [
        { id: 101, name: 'financial_services', allowed: true, description_en: 'Financial Services' },
        { id: 102, name: 'gambling', allowed: false, description_en: 'Gambling & Betting' },
        { id: 103, name: 'cryptocurrency', allowed: true, flagged: true, description_en: 'Cryptocurrency & Blockchain' }
      ]
    })
  });
  ```
</CodeGroup>

***

## Create Tenant (Admin Only)

Create a new tenant with full configuration.

### Endpoint

```
POST /kyc/tenants
```

### Request Body Parameters

<ParamFields>
  <ParamField name="tenant_id" type="string" required description="Unique tenant identifier" />

  <ParamField name="name" type="string" required description="Tenant display name" />

  <ParamField name="status" type="string" description="Status: 'active', 'suspended', or 'inactive' (default: 'active')" />

  <ParamField name="notification_config" type="object" description="Notification configuration" />

  <ParamField name="keywords" type="array" description="Array of keyword objects" />

  <ParamField name="industries" type="array" description="Array of industry objects" />

  <ParamField name="risk_matrix" type="object" description="Risk matrix configuration" />

  <ParamField name="website_config" type="object" description="Website validation configuration" />

  <ParamField name="billing_config" type="object" description="Billing configuration (admin only)" />
</ParamFields>

### Request Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.kyc.example.com/kyc/tenants",
      headers={
          "Authorization": f"Bearer {admin_token}",
          "Content-Type": "application/json"
      },
      json={
          "tenant_id": "new-tenant-123",
          "name": "New Company Inc.",
          "status": "active",
          "notification_config": {
              "notification_emails": ["admin@newcompany.com"]
          },
          "risk_matrix": {
              "ssl_weight": 0.30,
              "industry_weight": 0.70
          },
          "website_config": {
              "adverse_media_enabled": False,
              "sanction_check_enabled": True
          },
          "billing_config": {
              "plan_type": "MONTHLY",
              "contracted_limits": {
                  "kyc_checks": 100,
                  "adverse_media_checks": 50
              },
              "credits": {
                  "kyc_checks": 10,
                  "adverse_media_checks": 5
              }
          }
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kyc.example.com/kyc/tenants', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${adminToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tenant_id: 'new-tenant-123',
      name: 'New Company Inc.',
      status: 'active',
      notification_config: {
        notification_emails: ['admin@newcompany.com']
      },
      billing_config: {
        plan_type: 'MONTHLY',
        credits: { kyc_checks: 10 }
      }
    })
  });
  ```
</CodeGroup>

***

## Update Billing Configuration (Admin Only)

Update billing settings for a tenant.

### Endpoint

```
PATCH /kyc/tenants/{tenant_id}/billing
```

### Request Body Parameters

<ParamFields>
  <ParamField name="plan_type" type="string" description="Billing plan: 'MONTHLY', 'YEARLY', or 'CUSTOM'" />

  <ParamField name="billing_cycle_date" type="integer" description="Day of month for billing cycle (1-28)" />

  <ParamField name="contracted_limits" type="object" description="Monthly usage limits">
    <ParamField name="kyc_checks" type="integer" description="Monthly KYC checks limit" />

    <ParamField name="watchlist_scans" type="integer" description="Monthly watchlist scans limit" />

    <ParamField name="adverse_media_checks" type="integer" description="Monthly adverse media checks limit" />

    <ParamField name="batch_jobs" type="integer" description="Monthly batch jobs limit" />
  </ParamField>

  <ParamField name="usage_alerts" type="object" description="Usage alert configuration">
    <ParamField name="enabled" type="boolean" description="Enable usage alerts" />

    <ParamField name="thresholds" type="array" description="Alert percentage thresholds (e.g., [75, 90, 95])" />
  </ParamField>

  <ParamField name="watchlist_config" type="object" description="Watchlist seats configuration">
    <ParamField name="available_seats" type="integer" description="Total available monitoring seats" />

    <ParamField name="default_duration_days" type="integer" description="Default monitoring duration in days" />
  </ParamField>

  <ParamField name="credits" type="object" description="One-time validation credits">
    <ParamField name="kyc_checks" type="integer" description="KYC check credits" />

    <ParamField name="adverse_media_checks" type="integer" description="Adverse media check credits" />

    <ParamField name="crypto_checks" type="integer" description="Crypto check credits" />

    <ParamField name="web_validations" type="integer" description="Web validation credits" />
  </ParamField>

  <ParamField name="subscription" type="object" description="Subscription information">
    <ParamField name="product_id" type="string" description="Subscription product ID" />

    <ParamField name="status" type="string" description="Status: 'none', 'active', 'past_due', 'cancelled'" />

    <ParamField name="current_period_start" type="string" description="Period start (ISO8601)" />

    <ParamField name="current_period_end" type="string" description="Period end (ISO8601)" />

    <ParamField name="limits" type="object" description="Subscription usage limits" />
  </ParamField>
</ParamFields>

### Request Example

```python theme={null}
import requests

response = requests.patch(
    f"https://api.kyc.example.com/kyc/tenants/{tenant_id}/billing",
    headers={
        "Authorization": f"Bearer {admin_token}",
        "Content-Type": "application/json"
    },
    json={
        "plan_type": "MONTHLY",
        "contracted_limits": {
            "kyc_checks": 1000,
            "adverse_media_checks": 500
        },
        "usage_alerts": {
            "enabled": True,
            "thresholds": [75, 90, 95]
        },
        "watchlist_config": {
            "available_seats": 100,
            "default_duration_days": 365
        },
        "credits": {
            "kyc_checks": 50,
            "adverse_media_checks": 25
        }
    }
)
```

***

## Delete Tenant (Admin Only)

Soft-delete (deactivate) a tenant.

### Endpoint

```
DELETE /kyc/tenants/{tenant_id}
```

### Request Example

```bash theme={null}
curl -X DELETE https://api.kyc.example.com/kyc/tenants/tenant123 \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

### Response Format

```json theme={null}
{
  "status": "success",
  "data": {
    "message": "Tenant tenant123 deactivated successfully"
  }
}
```

***

## Permissions Reference

| Permission                     | Description                               |
| ------------------------------ | ----------------------------------------- |
| `tenant:manage`                | Full admin access to all tenant endpoints |
| `tenant:read`                  | Read own tenant configuration             |
| `notification-channels:read`   | Read notification settings                |
| `notification-channels:update` | Update notification settings              |
| `keywords:read`                | Read keywords                             |
| `keywords:update`              | Update keywords                           |
| `industries:read`              | Read industries                           |
| `industries:update`            | Update industries                         |
| `risk-matrix:read`             | Read risk matrix                          |
| `risk-matrix:update`           | Update risk matrix                        |
| `website-config:read`          | Read website config                       |
| `website-config:update`        | Update website config                     |
| `billing:read`                 | Read billing information                  |
| `billing:update`               | Update billing configuration              |

***

## Status Codes

| Code | Description                                          |
| ---- | ---------------------------------------------------- |
| 200  | Success                                              |
| 201  | Created - Tenant created successfully                |
| 400  | Bad Request - Invalid parameters or validation error |
| 401  | Unauthorized - Missing or invalid token              |
| 403  | Forbidden - Insufficient permissions                 |
| 404  | Not Found - Tenant not found                         |
| 409  | Conflict - Tenant already exists                     |
| 500  | Internal Server Error                                |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Account Status" icon="chart-pie">
    Use `/me/account-status` for dashboard displays - it provides all relevant information in a single call.
  </Card>

  <Card title="Risk Matrix Design" icon="scale-balanced">
    Design your risk matrix weights to sum exactly to 1.0. Only include weights for checks you actually use.
  </Card>

  <Card title="Webhook Security" icon="shield-halved">
    Always verify webhook signatures using your `webhook_secret`. It's auto-generated for security.
  </Card>

  <Card title="List Replacement" icon="arrows-rotate">
    Keywords and industries are fully replaced on update. Include all items when updating.
  </Card>
</CardGroup>

## Integration Tips

1. **Configuration Hierarchy**: Website config sets defaults → Request parameters override defaults
2. **Credit Priority**: Free tier credits are used after subscription quota is exhausted
3. **Watchlist Seats**: Track `remaining_seats` to prevent over-enrollment
4. **Risk Matrix**: Weights dynamically adjust based on which checks are enabled in the request
5. **Audit Trail**: `created_by` and `updated_by` fields track who made changes