Skip to main content

Accreditations

Accreditations represent background checks, compliance verifications, and clearance records in Oho. They are the verification results that confirm whether someone is authorized for specific activities or roles.

What is an Accreditation?​

An accreditation is a verification record that contains the results of a background check or compliance screening.

Key Characteristics:

  • Verification record - Represents a specific check (WWC, police, NDIS, etc.)
  • Contains results - Stores status, registry response, and verification details
  • Event-based - Created when a check is submitted
  • Historical - Immutable once completed (audit trail)
  • Optionally linked - Can be linked to a constituent or exist standalone

Real-World Examples:

  • A Victoria Working With Children Check verification
  • An NDIS Worker Screening result
  • A Visa Right to Work verification
  • An AHPRA health practitioner registration verification

Why Accreditations Exist​

Accreditations serve several critical purposes in Oho:

1. Verification Results Storage​

Accreditations store the actual outcomes of background checks:

Accreditation #12345
├── Type: Victorian WWC
├── Status: Completed
├── Registry Response:
│   ├── May Engage: Yes
│   ├── Oho Status: Active
│   └── Expiry: 2027-06-15
└── Completed At: 2024-01-15T10:30:00Z

2. Compliance Tracking​

Organizations use accreditations to demonstrate compliance:

Constituent: Sarah Chen
└── Accreditations
    ├── VIC WWC (Active, expires 2027)  ✓
    └── NDIS Screening (Cleared, 2024)  ✓

Compliance Status: ✓ Fully compliant

3. Audit Trail​

Accreditations provide a complete verification history:

Timeline:
2024-01-15: VIC WWC submitted → Completed (Active)
2024-06-20: NDIS Screening submitted → Completed (Cleared)
2025-01-10: VIC WWC renewal submitted → Completed (Active)

4. Real-Time Status​

Accreditations reflect current verification status:

  • Active clearances
  • Expired certifications
  • Suspended or cancelled registrations
  • Failed verification attempts

Complete Field Reference​

Core Fields​

FieldTypeRequiredDescription
idintegerAuto-generatedUnique accreditation identifier
typestringYesCheck type code (e.g., "vicwwc", "nswwwc", "ndis")
identifierstringYesCard/application number being verified
statusstringYesProcessing status: "pending", "in_progress", "completed", "failed", "expired"
correlation_idUUIDAuto-generatedUnique tracking ID for this verification request
created_attimestampAuto-generatedISO 8601 timestamp when check was submitted
updated_attimestampAuto-generatedISO 8601 timestamp of last update

Relationship Fields​

FieldTypeRequiredDescription
constituent_idintegerNoLinks to constituent (nullable for standalone checks)

Result Fields​

FieldTypeDescription
registry_responseobjectResponse data from government registry (varies by type)
errorobjectError details if check failed (null if successful)
completed_attimestampWhen check reached "completed" status
failed_attimestampWhen check reached "failed" status

Registry Response Object​

The registry_response structure varies by check type, but typically includes:

Common Fields:

{
  "may_engage": true,              // boolean - Can work with children/vulnerable people
  "oho_status": "active",          // string - Normalized status
  "response": ["Current", "May Engage"],  // array - Status messages
  "expiry_date": "2027-06-15",     // string - When clearance expires
  "card_type": "employee_wwc"      // string - Type of clearance
}

State-Specific Fields:

  • VIC: card_type, may_engage
  • NSW: birth_date_required, age_requirement_met
  • QLD: exemption, blue_card_type
  • And more...

See WWC Check Types for complete state-by-state details.

Error Object​

When a check fails, the error object provides details:

{
  "code": "invalid_identifier",
  "message": "The WWC card number provided could not be found in the registry",
  "details": {
    "field": "identifier",
    "provided": "9999999Z",
    "hint": "Double-check the card number and try again"
  }
}

Accreditation Types​

Oho supports multiple verification types across Australia:

Working With Children (WWC) Checks​

State/TerritoryType CodeDescription
VictoriavicwwcVictorian Working with Children Check
New South WalesnswwwcNSW Working with Children Check
QueenslandqldblueQueensland Blue Card (Standard)
QueenslandqldblueexQueensland Blue Card (Exemption)
South AustraliasawwcSA Working with Children Check
Western AustraliawawwcWA Working with Children Check
TasmaniataswwcTasmanian Working with Children Check
Northern TerritoryntwwcNT Working with Children Check
ACTactwwcACT Working with Children Check

Learn more about WWC Checks →

Other Verification Types​

TypeType CodeDescription
NDIS ScreeningndisNDIS Worker Screening Check
Visa CheckvisaVisa and Right to Work verification

Explore all check types →

Accreditation Status Values​

Accreditations progress through different statuses:

Pending​

{
  "status": "pending",
  "completed_at": null,
  "failed_at": null
}

Meaning:

  • Check has been received
  • Queued for processing
  • No results yet

Duration: Usually seconds to minutes

In Progress​

{
  "status": "in_progress",
  "completed_at": null,
  "failed_at": null
}

Meaning:

  • Currently querying government registry
  • Processing verification
  • Still waiting for results

Duration: Usually seconds to a few minutes

Completed​

{
  "status": "completed",
  "registry_response": { ... },
  "error": null,
  "completed_at": "2024-11-05T10:30:00Z",
  "failed_at": null
}

Meaning:

  • Check successfully completed
  • Results available in registry_response
  • Final state (immutable)

Next Steps: Review registry_response for clearance status

Failed​

{
  "status": "failed",
  "registry_response": null,
  "error": { ... },
  "completed_at": null,
  "failed_at": "2024-11-05T10:30:00Z"
}

Meaning:

  • Check could not be completed
  • Error details in error object
  • Final state (immutable)

Common Reasons:

  • Invalid card number
  • Name mismatch
  • Registry unavailable
  • Missing required fields

Expired​

{
  "status": "expired",
  "registry_response": {
    "oho_status": "expired",
    "expiry_date": "2024-06-15"
  },
  "completed_at": "2024-01-15T10:30:00Z"
}

Meaning:

  • Clearance has expired
  • Was previously valid
  • Renewal required

Action: Submit a new check for renewal

Accreditation Lifecycle​

Standard Workflow (Async)​

1. Submit Check
   POST /api/scan/{type}
   ↓
2. Receive Correlation ID
   Response: { "correlation_id": "uuid..." }
   Status: pending
   ↓
3. Background Processing
   Oho queries government registry
   Status: in_progress
   ↓
4. Webhook Notification
   POST https://your-webhook.com
   Status: completed or failed
   ↓
5. Retrieve Results
   GET /accreditations/{id}
   View registry_response

Timeline: Usually 2-10 seconds for WWC checks

Synchronous Workflow (Testing)​

1. Submit Sync Check
   POST /sync_scan/wwc
   ↓
2. Wait for Completion
   (Request blocks until complete)
   ↓
3. Receive Complete Results
   Response includes full accreditation
   with registry_response

Use Case: Testing and debugging only (not for production)

State Transitions​

        ┌─────────┐
        │ pending │
        └────┬────┘
             │
             ▼
     ┌──────────────┐
     │ in_progress  │
     └──────┬───────┘
            │
        ┌───┴───┐
        │       │
        ▼       ▼
   ┌──────┐  ┌────────┐
   │ completed │  │ failed │
   └──────┘  └────────┘
      │
      │ (after expiry date)
      ▼
   ┌─────────┐
   │ expired │
   └─────────┘

Important: completed and failed are terminal states (immutable)

Example Accreditation Objects​

Example 1: Completed WWC Check​

{
  "id": 5354,
  "constituent_id": 113767,
  "type": "vicwwc",
  "identifier": "1076131A",
  "status": "completed",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "registry_response": {
    "may_engage": true,
    "response": ["Current", "May Engage"],
    "oho_status": "active",
    "card_type": "employee_wwc",
    "expiry_date": "2027-06-15"
  },
  "error": null,
  "completed_at": "2024-11-01T12:00:45Z",
  "failed_at": null,
  "created_at": "2024-11-01T12:00:00Z",
  "updated_at": "2024-11-01T12:00:45Z"
}

Example 2: Failed WWC Check​

{
  "id": 5355,
  "constituent_id": 113768,
  "type": "nswwwc",
  "identifier": "WWC9999999",
  "status": "failed",
  "correlation_id": "c4ca4238-a0b9-2382-0dcc-509a6f75849b",
  "registry_response": null,
  "error": {
    "code": "not_found",
    "message": "WWC number not found in NSW registry",
    "details": {
      "identifier": "WWC9999999",
      "hint": "Verify the card number and try again"
    }
  },
  "completed_at": null,
  "failed_at": "2024-11-01T12:05:00Z",
  "created_at": "2024-11-01T12:04:50Z",
  "updated_at": "2024-11-01T12:05:00Z"
}

Example 3: Standalone Accreditation (No Constituent)​

{
  "id": 5356,
  "constituent_id": null,  // ← No constituent link
  "type": "qldblue",
  "identifier": "BLUE123456",
  "status": "completed",
  "correlation_id": "1c574d2a-24e3-447f-8b2f-d43ed7f9ee4e",
  "registry_response": {
    "may_engage": true,
    "oho_status": "active",
    "card_type": "blue_card",
    "expiry_date": "2026-12-31"
  },
  "error": null,
  "completed_at": "2024-11-01T13:00:00Z",
  "failed_at": null,
  "created_at": "2024-11-01T12:59:50Z",
  "updated_at": "2024-11-01T13:00:00Z"
}

Relationships​

Accreditation → Constituent (N:1, Optional)​

An accreditation can optionally link to a constituent:

Constituent (const_123 - Sarah Chen)
├── Accreditation (acc_001) - VIC WWC
└── Accreditation (acc_002) - NDIS Screening

Standalone Accreditations (no constituent link)
├── Accreditation (acc_999) - One-off verification
└── Accreditation (acc_1000) - Another standalone check

Foreign Key: accreditation.constituent_id → constituent.id (nullable)

Benefits of Linking:

  • Centralized person record
  • Historical tracking
  • Easier compliance reporting
  • Auto-enrichment of constituent data

Benefits of Standalone:

  • Quick one-off verifications
  • No need to create constituent first
  • Simpler for single checks

Accreditation → Organization (N:1, Implicit)​

All accreditations are scoped to the authenticated organization:

Organization (org_123)
├── Accreditations via Constituents
│   ├── Accreditation (linked to const_001)
│   └── Accreditation (linked to const_002)
└── Standalone Accreditations
    └── Accreditation (no constituent)

Scoping: Enforced via API authentication (cannot access other organizations' accreditations)

Common Patterns​

Recommended for employee/volunteer tracking:

POST /api/scan/{type}
{
  "state": "vic",
  "identifier": "1234567A",
  "first_name": "Sarah",
  "surname": "Chen",
  "birth_date": "1992-03-15",
  "constituent": { "id": 113767 }  // ← Links to constituent
}

Benefits:

  • Links accreditation to person record
  • Auto-updates constituent fields (if null)
  • Easier to track compliance

Pattern 2: Submit Standalone Check​

Useful for one-off verifications:

POST /api/scan/{type}
{
  "state": "nsw",
  "identifier": "WWC1234567",
  "first_name": "John",
  "surname": "Smith",
  "birth_date": "1985-07-20"
  // No constituent.id
}

Benefits:

  • Faster (no constituent creation needed)
  • Simple for one-time checks
  • Still tracked and auditable

Pattern 3: Poll for Results (Alternative to Webhooks)​

If webhooks not available, poll using correlation_id:

# Step 1: Submit check
POST /api/scan/{type}
Response: { "correlation_id": "uuid-123" }

# Step 2: Poll for results
GET /accreditations?correlation_id=uuid-123

# Step 3: Check status
If status == "completed" → Retrieve registry_response
If status == "failed" → Review error object
If status == "pending" or "in_progress" → Wait and retry

Recommended: Use webhooks instead for real-time updates

Pattern 4: Retrieve Accreditation by ID​

Direct access when you know the ID:

GET /accreditations/5354

Response: Complete accreditation object with results

Pattern 5: List Constituent's Accreditations​

View all checks for a person:

GET /constituents/113767

Response includes accreditations array with all linked accreditations

Pattern 6: Compliance Audit​

List all accreditations for reporting:

GET /accreditations?status=completed&created_after=2024-01-01

Filter by:

  • Status
  • Type
  • Date range
  • Constituent ID

Normalized Status Values​

The registry_response.oho_status field provides a normalized status across all states:

Oho StatusMeaningMay Work?
activeCurrent and valid clearance✅ Yes
inactiveNot currently active❌ No
expiredClearance has expired❌ No
suspendedTemporarily suspended❌ No
cancelledPermanently cancelled❌ No
pendingApplication pending⚠️ Interim may allow
interimInterim clearance granted✅ Yes (temporary)

Use oho_status for decision-making - it normalizes variations across states

Best Practices​

1. Use Webhooks for Real-Time Results​

Recommended:

Submit Check → Receive correlation_id → Continue work → Webhook delivers results

Not Recommended:

Submit Check → Poll every 5 seconds → Waste API calls → Get results eventually

2. Store Correlation IDs​

Track correlation IDs in your system:

{
  "employee_id": "EMP-123",
  "wwc_check_correlation_id": "uuid-123",
  "check_submitted_at": "2024-11-05T10:00:00Z",
  "status": "pending"
}

Benefits:

  • Link webhook callbacks to internal records
  • Retry failed checks
  • Audit trail

3. Handle Failed Checks Gracefully​

When status == "failed":

  1. Review error object
  2. Identify the issue (invalid number, name mismatch, etc.)
  3. Correct the issue
  4. Resubmit check with corrected data

Don't: Repeatedly submit the same invalid data

4. Monitor Expiry Dates​

Set up automated monitoring:

# Query all accreditations
GET /constituents

# For each constituent's accreditations:
For each accreditation:
  If expiry_date < (today + 30 days):
    Alert: "Renewal required soon"
  If expiry_date < today:
    Alert: "Clearance expired"

5. Treat Completed Accreditations as Immutable​

Once status == "completed":

  • Do not expect changes
  • Results are historical records
  • If status changes (e.g., suspension), submit a new check

6. Use oho_status for Decisions​

Don't parse state-specific responses:

Good:

if (accreditation.registry_response.oho_status === 'active') {
  // Allow work
}

Bad:

if (accreditation.registry_response.response.includes('Current')) {
  // Fragile - differs by state
}

Security & Privacy​

Data Sensitivity​

Accreditations contain sensitive verification data:

  • Personal identifiers (card numbers)
  • Background check results
  • Compliance status

Responsibilities:

  • Secure storage and transmission
  • Access controls (who can view results)
  • Audit logging (who accessed what)
  • Retention policies (how long to keep)

Compliance​

Accreditations help demonstrate compliance with:

  • Child Safety Standards
  • NDIS Worker Screening requirements
  • Employment law requirements
  • Duty of care obligations

Best Practices:

  • Verify clearances before employment/engagement
  • Monitor expiry and renewal
  • Document decision-making
  • Retain records for audit purposes

API Operations​

Accreditations can be accessed through multiple endpoints:

Next Steps​