Skip to main content

Organizations

Organizations are the top-level entity in Oho's data model. They represent the companies, institutions, or entities that use the Oho platform to manage compliance and background screening.

What is an Organization?​

An organization is the tenant container that holds all other data in Oho. Think of it as your company's account on the platform.

Key Characteristics:

  • Top of the hierarchy - Constituents and users belong to an organization
  • Data isolation boundary - Each organization's data is completely separate from others
  • Billing entity - Subscriptions are tracked per organization
  • Security context - All API operations are scoped to an organization

Real-World Examples:

  • A healthcare provider managing staff WWC checks
  • A school verifying teacher registrations
  • An aged care facility tracking NDIS worker screening
  • A recruitment agency conducting pre-employment checks

Why Organizations Exist​

Organizations serve several critical purposes in Oho:

1. Multi-Tenancy​

Oho is a multi-tenant platform where multiple customers share the same infrastructure but have completely isolated data.

Oho Platform
├── Organization A (Hospital)
│   └── 500 constituents (with claims to accreditations)
├── Organization B (School)
│   └── 150 constituents (with claims to accreditations)
└── Organization C (Agency)
    └── 2,000 constituents (with claims to accreditations)

Each organization cannot see or access the others' data.

2. Data Isolation​

Every API call operates within an organization context:

  • Your authentication token identifies your organization
  • All queries are automatically filtered to your organization
  • You can never access another organization's constituents or checks
  • This ensures complete privacy and security

3. Subscription Management​

Organizations are the unit of billing:

  • Subscription plans apply to organizations
  • Billing is managed at the organization level
  • Rate limiting is applied per authenticated user

4. Configuration & Settings​

Organizations have independent configurations:

  • SAML providers (Okta, Azure AD, etc.)
  • Webhook endpoints
  • Notification preferences

Organization Status​

Organizations can be in one of two states:

Active​

{
  "id": "org_123",
  "status": "active"
}

Capabilities:

  • ✅ Submit background checks
  • ✅ Create and manage constituents
  • ✅ Access API endpoints
  • ✅ Receive webhook notifications
  • ✅ Generate reports

Inactive​

{
  "id": "org_456",
  "status": "inactive"
}

Limitations:

  • ❌ Cannot submit new background checks
  • ❌ Cannot create new constituents
  • ✅ Can read existing data (read-only)
  • ❌ No webhook notifications
  • ✅ API access restricted to read operations

Why Inactive?

  • Subscription expired
  • Account suspended (non-payment, policy violation)
  • Organization voluntarily paused
  • Administrative hold

Relationships​

Organization → Constituents (1:N)​

An organization can have unlimited constituents:

Organization (org_123)
├── Constituent (const_001) - John Smith
├── Constituent (const_002) - Sarah Chen
├── Constituent (const_003) - Alice Wong
└── ...1,000+ more

Operations:

  • List all constituents: GET /constituents
  • Each constituent belongs to exactly one organization
  • Cannot transfer constituents between organizations

Organization → Accreditations (indirect via claims)​

Organizations access accreditations through their constituents' claims:

Organization (org_123)
└── Constituents
    ├── Constituent (const_001)
    │   └── Claims
    │       └── Accreditation (acc_001) - VIC WWC
    └── Constituent (const_002)
        └── Claims
            └── Accreditation (acc_003) - NSW WWC

Note: The same accreditation can be claimed by constituents in different organizations

Data Access: Accreditations are accessed through the organization's constituents

Organization → Users (1:N)​

An organization can have multiple users with different roles:

Organization (org_123)
├── User (admin@example.com) - Admin
├── User (manager@example.com) - Manager
└── User (staff@example.com) - Staff

Roles & Permissions:

  • Admin: Full access to all features
  • Manager: Create/update constituents, submit checks, view reports
  • Staff: View-only access

Organization → Webhooks (1:1)​

An organization can configure a webhook endpoint for real-time notifications:

Organization (org_123)
└── Webhook Configuration
    ├── URL: https://api.example.com/oho/webhook
    └── Receives all accreditation validation events

Multi-Site Organizations​

Some organizations have multiple physical sites but one Oho account:

Organization (Healthcare Group)
├── Constituents
│   ├── Alice (employee_id: "SITE-A-001", works at Site A)
│   ├── Bob (employee_id: "SITE-B-002", works at Site B)
│   └── Carol (employee_id: "SITE-A-003", works at Site A)
└── Use employee_id to track site location

Approach: Use constituent.employee_id to denote site/location

API Operations​

For detailed API documentation, see:

Best Practices​

1. Single Organization per Customer​

Recommended: One organization per customer/tenant

  • Simplifies billing and usage tracking
  • Clear data boundaries
  • Independent configuration

Not Recommended: Multiple organizations for one customer

  • Complicates reporting across organizations
  • Duplicate configuration management
  • More complex API integration

2. Keep Organization Active​

Ensure subscription and compliance:

  • Monitor subscription expiry dates
  • Renew before expiration
  • Address any policy violations promptly
  • Inactive status blocks all check submissions

3. Configure Webhooks​

Enable webhooks for real-time updates:

  • Receive immediate notification when checks complete
  • Avoid polling for status updates
  • More efficient API usage
  • Better user experience

4. Secure Contact Information​

Keep contact information current:

  • Used for important notifications
  • Subscription renewal reminders
  • Security alerts
  • Platform updates

5. Configure Security Settings​

Configure settings to match your security requirements:

  • Enable 2FA for sensitive data
  • Configure SAML for enterprise SSO
  • Set up webhook endpoint for real-time updates

Security Considerations​

Data Isolation​

Guaranteed: Your organization's data is completely isolated from all other organizations.

Enforcement:

  • API authentication scoped to organization
  • Query filters automatically applied
  • No cross-organization access possible

Access Control​

Who can access organizations?

  • Admins: Full access to their own organization settings
  • Managers/Staff: Limited access to their own organization
  • Oho Platform Admins: Can view and update all organizations

Next Steps​