Skip to main content

Constituents

Constituents represent individual people within an organization who require background checks or compliance screening. They are the "person records" that link to accreditations and store personal information.

What is a Constituent?​

A constituent is an individual person record in Oho that stores personal identifying information (PII) and serves as the subject of background checks.

Key Characteristics:

  • Person entity - Represents an individual (staff member, volunteer, contractor)
  • Subject of checks - The person being screened or verified
  • PII storage - Stores name, date of birth, contact details
  • Parent of accreditations - Links to multiple background checks over time
  • Belongs to one organization - Cannot be shared across organizations

Real-World Examples:

  • A nurse being verified for AHPRA registration and WWC clearance
  • A teacher undergoing Working With Children Check
  • A contractor requiring NDIS Worker Screening

Why Constituents Exist​

Constituents serve several important purposes in Oho:

1. Central Person Record​

Constituents provide a single source of truth for an individual's information:

Constituent: Sarah Chen
├── Personal Details (name, DOB, email)
├── Contact Information (phone, address)
├── Employment Reference (employee_id)
└── Accreditations History
    ├── VIC WWC (2024-01-15) ✓ Active
    └── NDIS Screening (2024-03-10) ✓ Active

Constituents connect an organization to its verification records:

Organization → Constituent → Accreditations
(Healthcare)   (Sarah Chen)  (WWC, NDIS)

3. Auto-Enrichment Target​

When submitting checks with a constituent ID, Oho may update the constituent record:

  • Updates fields like date_of_birth, mobile_number, email from check data
  • Maintains data completeness over time
  • Note: Updates replace existing values and cannot be undone via the UI

4. Accreditation Linking​

Constituents serve as the link between your organization and accreditation records:

Constituent → Claims → Accreditations
  (Person)     (Links)  (Verification Records)

Core Fields​

Constituents have the following key fields:

  • id - Unique constituent identifier
  • first_name - Given name
  • last_name - Family name/surname
  • email - Email address (must be unique within organization)
  • phone - Phone number
  • mobile_number - Mobile phone number
  • date_of_birth - Date of birth (YYYY-MM-DD format, required for some check types)
  • external_id - Your internal employee/contractor ID for cross-referencing
  • active - Boolean indicating if constituent is currently active

Note: date_of_birth is required for some check types (NSW WWC, SA WWC).

Constituent Status​

Constituents have an active field (boolean):

Active (true)​

Meaning:

  • Currently employed/engaged
  • Eligible for background checks
  • Displayed in active staff lists
  • Included in compliance reports

Inactive (false)​

Meaning:

  • No longer employed/engaged
  • Historical record maintained
  • Can still view accreditation history
  • Excluded from active compliance reports

Why Inactive?

  • Employment ended
  • Contractor engagement completed
  • Volunteer role concluded

Relationships​

Constituent → Organization (N:1)​

Each constituent belongs to exactly one organization:

Organization (org_123)
├── Constituent (const_001)
├── Constituent (const_002)
└── Constituent (const_003)

Rules:

  • Cannot access constituents from other organizations
  • Data is scoped to your authenticated organization

Constituent → Accreditations (via Claims)​

A constituent can claim multiple accreditations over time:

Constituent (const_567 - Michael Thompson)
└── Claims
    ├── Accreditation (9001) - VIC WWC
    ├── Accreditation (9002) - NDIS Screening
    └── Accreditation (9003) - QLD Blue Card

Rules:

  • Constituent can have unlimited accreditation claims
  • Accreditations are always linked via claims
  • The same accreditation can be claimed by multiple constituents

Constituent Lifecycle​

Creation and Onboarding​

1. New Hire/Volunteer
   ↓
2. Create Constituent Record
   POST /constituents/ensure_exists
   ↓
3. Submit Initial Background Checks
   POST /api/scan
   ↓
4. Monitor Completion
   Receive webhook notifications
   ↓
5. Verify Compliance
   GET /constituents/{id}
   View linked accreditations

Ongoing Compliance​

Active Constituent
   ↓
Monitor Accreditation Status
   ↓
Renewal Required?
   ├─ Yes → Submit Renewal Check
   └─ No → Continue monitoring

Offboarding​

Employment Ends
   ↓
Set active to false
   PATCH /constituents/{id}
   { "active": false }
   ↓
Historical Record Retained
   (for audit trail)

Common Patterns​

Pattern 1: Creating a Constituent​

Create a person record before submitting checks:

POST /constituents/ensure_exists
Content-Type: application/json

{
  "first_name": "Emma",
  "last_name": "Rodriguez",
  "email": "emma.rodriguez@example.com",
  "phone": "+61-2-9876-5432",
  "date_of_birth": "1992-05-14",
  "external_id": "EMP-2024-789"
}

Response:

{
  "id": 890,
  "first_name": "Emma",
  "last_name": "Rodriguez",
  "active": true,
  "created_at": "2024-11-05T10:00:00Z",
  ...
}

Pattern 2: Linking Checks to Constituent​

Submit checks with constituent ID to link:

POST /api/scan
{
  "type": "actwwc",
  "identifier": "WWC1234567",
  "first_name": "Emma",
  "surname": "Rodriguez",
  "birth_date": "1992-05-14",
  "constituent": { "id": 890 }  // ← Links to constituent
}

Pattern 3: Viewing Complete Compliance Record​

Fetch constituent with all accreditations:

GET /constituents/890

Response includes:

  • Personal details
  • Contact information
  • Linked accreditation data

Pattern 4: Minimal Constituent​

Create with minimal information:

# Step 1: Create minimal constituent
POST /constituents/ensure_exists
{
  "first_name": "Tom",
  "last_name": "Wilson",
  "email": "tom.wilson@example.com"
  // No DOB provided initially
}

# Response: constituent created with id 999

# Step 2: Submit check with full details
POST /api/scan
{
  "type": "vicwwc",
  "identifier": "9876543A",
  "first_name": "Tom",
  "surname": "Wilson",
  "birth_date": "1990-08-05",
  "constituent": { "id": 999 }
}

# The constituent record may be updated with DOB from the check

Validation Rules​

Email Uniqueness​

  • Email must be unique within an organization
  • Can have duplicate emails across different organizations
  • Prevents accidental duplicate records

API Operations​

Constituents support standard CRUD operations. For detailed API documentation, see:

Best Practices​

1. Create Constituents First​

Recommended workflow:

1. Create constituent record
2. Submit background checks (linked)
3. Monitor via webhooks
4. View complete record (constituent + accreditations)

Benefits:

  • Central person record
  • Historical tracking
  • Auto-enrichment
  • Easier reporting

2. Use External IDs​

Link to your internal systems:

{
  "email": "john.smith@example.com",
  "external_id": "EMP-2024-1234"  // ← Your internal ID
}

Benefits:

  • Easy cross-reference with HR systems
  • Unique identifier beyond email
  • Supports API integrations

3. Keep Active Status Current​

Update active field when employment changes:

# Employee leaves
PATCH /constituents/{id}
{ "active": false }

Benefits:

  • Accurate compliance reports
  • Clear active vs historical records
  • Better data management

4. Create Constituents First​

Create constituent records before submitting checks:

  • Create constituent with basic info
  • Submit checks linked to the constituent
  • View complete compliance history in one place

Benefits:

  • Maintains consistency
  • Easier reporting
  • Complete audit trail

Privacy Considerations​

Personal Information​

Constituents store Personally Identifiable Information (PII):

  • Names, dates of birth
  • Email addresses, phone numbers

Organization Responsibilities:

  • Comply with Australian Privacy Principles
  • Implement appropriate access controls
  • Secure storage and transmission

Data Access​

Who can access constituent data?

  • Users within the same organization (with appropriate role)
  • API clients authenticated to the organization
  • Never accessible to other organizations

Right to Access and Correction​

Individuals may request:

  • Access to their constituent record
  • Correction of inaccurate information

Handle these requests via API:

  • GET /constituents/{id} - Provide data access
  • PATCH /constituents/{id} - Correct information
  • DELETE /constituents/{id} - Inactivate constituent record (sets active: false)

Next Steps​