Tenants

Manage organizations (tenants) and their members with role-based access control. Each tenant receives complete database isolation with schema-per-tenant architecture for regulatory compliance and security.

The tenant model

The tenant model contains all the information about your organizations, including business details, member roles, and isolated database schema configuration.

Properties

Name
id
Type
string
Description
Unique identifier for the tenant.
Name
name
Type
string
Description
Organization name (displayed in UI and reports).
Name
slug
Type
string
Description
URL-friendly identifier for the tenant.
Name
business_type
Type
string
Description
Business type: wallet, exchange, lending, payment_processor, or other.
Name
description
Type
string
Description
Optional description of the organization.
Name
status
Type
string
Description
Tenant status: active, suspended, or pending_setup.
Name
created_at
Type
timestamp
Description
Timestamp of when the tenant was created.
Name
members
Type
array
Description
Array of tenant members with their roles (only included in detailed responses).

GET/v1/tenants

List all tenants

Retrieve all tenants where the authenticated user is a member. Returns only tenants where the user has membership with their role information.

Optional attributes

Name
status
Type
string
Description
Filter by tenant status: active, suspended, or pending_setup.
Name
business_type
Type
string
Description
Filter by business type.
Name
limit
Type
integer
Description
Number of results to return (default: 50, max: 100).
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

GET

/v1/tenants

curl -G https://api.sandbox.whocomply.com/v1/tenants \
  -H "Authorization: Bearer {token}" \
  -d business_type=wallet \
  -d limit=10

Response

{
  "success": true,
  "data": {
    "tenants": [
      {
        "id": "tenant_01JB2M3N4P5Q6R7S8T9U0V",
        "name": "ACME Fintech Limited",
        "slug": "acme-fintech",
        "business_type": "wallet",
        "status": "active",
        "user_role": "admin",
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": "tenant_02KC3M4N5P6Q7R8S9T0U1W",
        "name": "Beta Payment Co",
        "slug": "beta-payments",
        "business_type": "wallet",
        "status": "active",
        "user_role": "developer",
        "created_at": "2025-01-14T15:20:00Z"
      }
    ],
    "pagination": {
      "total": 2,
      "limit": 10,
      "offset": 0,
      "has_more": false
    }
  }
}

POST/v1/tenants

Create a tenant

Create a new organization with isolated database schema. The authenticated user automatically becomes the tenant admin. Each tenant receives a dedicated database schema for complete data isolation.

Required attributes

Name
name
Type
string
Description
Organization name (displayed in UI and reports).
Name
slug
Type
string
Description
URL-friendly identifier (auto-sanitized if needed).
Name
business_type
Type
string
Description
Business type: wallet, exchange, lending, payment_processor, or other.

Optional attributes

Name
description
Type
string
Description
Optional description of the organization.

Request

POST

/v1/tenants

curl https://api.sandbox.whocomply.com/v1/tenants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Fintech Limited",
    "slug": "acme-fintech",
    "business_type": "wallet",
    "description": "Digital wallet for Nigerian consumers"
  }'

Response

{
  "success": true,
  "data": {
    "tenant": {
      "id": "tenant_01JB2M3N4P5Q6R7S8T9U0V",
      "name": "ACME Fintech Limited",
      "slug": "acme-fintech",
      "business_type": "wallet",
      "description": "Digital wallet for Nigerian consumers",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z"
    }
  },
  "message": "Tenant created successfully with isolated database schema"
}

GET/v1/tenants/:id

Retrieve a tenant

Retrieve detailed information about a specific tenant, including member list and settings. Requires membership in the target tenant.

Request

GET

/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V

curl https://api.sandbox.whocomply.com/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "tenant": {
      "id": "tenant_01JB2M3N4P5Q6R7S8T9U0V",
      "name": "ACME Fintech Limited",
      "slug": "acme-fintech",
      "business_type": "wallet",
      "description": "Digital wallet for Nigerian consumers",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "members": [
        {
          "user_id": "user_01JB2M3N4P5Q6R7S8T9U0V",
          "email": "john.doe@acmefintech.com",
          "first_name": "John",
          "last_name": "Doe",
          "role": "admin",
          "status": "active",
          "joined_at": "2025-01-15T10:30:00Z"
        }
      ],
      "settings": {
        "default_currency": "NGN",
        "timezone": "Africa/Lagos"
      }
    }
  }
}

POST/v1/tenants/:id/members

Invite user to tenant

Add a new user to the tenant with specified role. Only admin users can invite others. The invited user must already have a registered account.

Required attributes

Name
email
Type
string
Description
Email address of user to invite (must be registered).
Name
role
Type
string
Description
Role to assign: admin, developer, readonly, or auditor.

Request

POST

/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members

curl https://api.sandbox.whocomply.com/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@acmefintech.com",
    "role": "developer"
  }'

Response

{
  "success": true,
  "data": {
    "member": {
      "user_id": "user_02KC3M4N5P6Q7R8S9T0U1W",
      "email": "developer@acmefintech.com",
      "role": "developer",
      "status": "active",
      "joined_at": "2025-01-15T11:00:00Z"
    }
  },
  "message": "User added to tenant successfully"
}

PUT/v1/tenants/:id/members/:user_id

Update member role

Change a member's role within the tenant. Only admin users can update roles.

Required attributes

Name
role
Type
string
Description
New role: admin, developer, readonly, or auditor.

Request

PUT

/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members/user_02KC3M4N5P6Q7R8S9T0U1W

curl -X PUT https://api.sandbox.whocomply.com/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members/user_02KC3M4N5P6Q7R8S9T0U1W \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Response

{
  "success": true,
  "data": {
    "member": {
      "user_id": "user_02KC3M4N5P6Q7R8S9T0U1W",
      "role": "admin",
      "updated_at": "2025-01-15T11:30:00Z"
    }
  },
  "message": "Member role updated successfully"
}

DELETE/v1/tenants/:id/members/:user_id

Remove member

Remove a user from the tenant. Admins can remove any member; users can remove themselves.

Request

DELETE

/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members/user_02KC3M4N5P6Q7R8S9T0U1W

curl -X DELETE https://api.sandbox.whocomply.com/v1/tenants/tenant_01JB2M3N4P5Q6R7S8T9U0V/members/user_02KC3M4N5P6Q7R8S9T0U1W \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Member removed from tenant successfully"
}