Skip to main content

5-Minute Quickstart

Get your first background check running in under 5 minutes. This guide takes you from account creation to receiving your first verification result.

What You'll Accomplish

By the end of this guide, you'll have:

  • ✅ Created and verified your Oho account
  • ✅ Generated an API token
  • ✅ Submitted your first background check
  • ✅ Received verification results

Step 1: Create Your Account (1 minute)​

  1. Visit weareoho.com and click "Sign Up" or "Get Started"

  2. Fill in your details:

    • Business email address
    • Secure password
    • Your name
    • Organization name

  3. Activate your subscription (optional):

    • You can start with a free trial to explore Oho's features
    • Click "Activate my subscription" in the top right when ready
    • Enter your organization details (ABN, address, phone)
    • Select your subscription plan
    • Add payment details (you won't be charged until the free trial ends)

  4. Verify your email:

    • Check your inbox for an email from noreply@weareoho.com
    • Check spam/junk folder if you don't see it
    • Click "Verify my email" to activate full platform access

  5. Sign in at app.weareoho.com/login

    • Use your email and password to access the platform
note

You must verify your email before you can access API credentials or submit checks. Don't have an ABN? Learn more about ABN

Step 2: Get Your JWT Token (1 minute)​

Oho uses JWT (JSON Web Token) authentication. You'll exchange your email and password for a token.

Quick Method: Using cURL​

# Step 1: Get your user ID
USER_ID=$(curl -s -X GET https://app.weareoho.com/api/users/me \
  -H "Authorization: Basic $(echo -n 'your-email@example.com:your-password' | base64)" \
  | grep -o '"id":[0-9]*' | grep -o '[0-9]*')

# Step 2: Get JWT token
curl -X POST https://app.weareoho.com/api/users/$USER_ID/token \
  -H "Authorization: Basic $(echo -n 'your-email@example.com:your-password' | base64)"

Replace:

  • your-email@example.com with your Oho email
  • your-password with your Oho password

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "iat": 1562725129,
  "exp": 1565317129
}
Keep Your Credentials Safe

Store your email, password, and tokens securely. Never commit them to version control or share them publicly. Use environment variables for credentials.

Your JWT token is the long string starting with eyJ... - copy this, you'll use it in the next step!

Step 3: Submit Your First Check (2 minutes)​

Let's verify a Working With Children Check (WWC). We'll use a Victorian WWC as an example.

Universal Endpoint

All WWC checks (all states) use the same /api/scan endpoint. Just change the type field for different states.

Option A: Using cURL (Command Line)​

curl -X POST https://app.weareoho.com/api/scan \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vicwwc",
    "identifier": "1076131A",
    "first_name": "John",
    "surname": "Smith"
  }'

Replace YOUR_JWT_TOKEN with the token from Step 2.

Option B: Using Python​

import requests

JWT_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
BASE_URL = "https://app.weareoho.com/api"

headers = {
    "Authorization": f"Bearer {JWT_TOKEN}",
    "Content-Type": "application/json"
}

# Submit a Victorian WWC check
response = requests.post(
    f"{BASE_URL}/scan",
    headers=headers,
    json={
        "type": "vicwwc",
        "identifier": "1076131A",
        "first_name": "John",
        "surname": "Smith"
    }
)

print(response.json())

Option C: Using JavaScript​

const JWT_TOKEN = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const BASE_URL = 'https://app.weareoho.com/api';

async function submitCheck() {
  const response = await fetch(`${BASE_URL}/scan`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${JWT_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'vicwwc',
      identifier: '1076131A',
      first_name: 'John',
      surname: 'Smith'
    })
  });

  const data = await response.json();
  console.log(data);
}

submitCheck();

Expected Response​

{
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}

What just happened?

  • Your check request was queued for processing
  • The system is now verifying the WWC against the Victorian registry
  • You received a correlation_id to track this request

Step 4: Receive Results (1 minute)​

Results are delivered via webhooks (real-time notifications) or you can poll for status.

Method A: Quick Status Check (Polling)​

You can check the accreditation details directly using the Oho web interface:

  1. Sign in to app.weareoho.com

  2. Navigate to the Accreditations page from the main menu

  3. Find your recent check using the correlation ID or constituent name

  4. View the status - it will show:

    • ✅ Green - Valid and current
    • ⚠️ Yellow - Expiring soon
    • ❌ Red - Expired, suspended, or not found

The check typically completes in 2-10 seconds. Refresh the page to see the latest status.

tip

For programmatic status checks, see the API Reference for querying accreditation status via API endpoints.

For production use, configure webhooks to receive results automatically:

  1. Create a webhook endpoint in your application to receive POST requests

  2. Configure the webhook in Oho:

curl -X POST https://app.weareoho.com/api/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/oho",
    "events": ["accreditation.completed", "accreditation.failed"]
  }'
  1. Receive results automatically:

When your check completes, Oho will POST to your webhook URL:

{
  "event": "accreditation_validation",
  "correlation_id": "d591aa45-64fa-46b9-8eab-423075ee66cb",
  "content": {
    "current": {
      "id": 20,
      "type": "qldblue",
      "identifier": "123456/7",
      "name": "Caring Person",
      "active": true,
      "expiry": "2020-03-15",
      "name_match": true,
      "status_color": "red",
      "status_flags": ["not_current"],
      "status_detail": {
        "found": false,
        "current": false,
        "expired": true,
        "expiring": false,
        "name_match": true,
        "messages": [
          "The card details provided cannot be validated.",
          "This information was current at 2:45am on 19/03/2020, query submitted 3:51pm on 19/03/2020"
        ]
      },
      "registry_response": {
        "response": "May Not Engage"
      },
      "latest_verification_event": {
        "event_ts": "2020-03-19T05:51:31.079000+00:00"
      }
    },
    "previous": {
      "id": 20,
      "type": "qldblue",
      "identifier": "123456/7",
      "name": "Caring Person",
      "active": true,
      "expiry": "2020-03-15",
      "name_match": true,
      "status_color": "yellow",
      "status_flags": ["expiring"],
      "status_detail": {
        "found": true,
        "current": true,
        "expired": false,
        "expiring": true,
        "name_match": true,
        "messages": [
          "125456/7 is a valid card.",
          "This information was current at 2:45am on 12/03/2020, query submitted 3:51pm on 12/03/2020"
        ]
      },
      "registry_response": {
        "response": "May Engage"
      },
      "latest_verification_event": {
        "event_ts": "2020-03-12T05:51:31.079000+00:00"
      }
    },
    "constituent": {
      "id": 333,
      "full_name": "Caring Person",
      "email": "caring.person@example.com",
      "organization": {
        "id": 25,
        "name": "Kinderoo Childcare"
      }
    }
  }
}

Key fields to understand:

  • event - Always "accreditation_validation" for check results
  • correlation_id - Matches the ID from your original submission
  • content.current - Current state of the accreditation
    • status_color - "green" (valid), "yellow" (expiring), "red" (expired/invalid)
    • status_flags - Quick indicators like "not_current", "expiring", etc.
    • status_detail.messages - Human-readable validation results
    • registry_response.response - Official registry determination (e.g., "May Engage" / "May Not Engage")
  • content.previous - Previous state (if this is an update to an existing check)
  • content.constituent - Person and organization details linked to this check

Understanding the Result​

Your WWC check result tells you:

FieldWhat It Means
status: "valid"The WWC is active and valid
expiry_dateWhen the clearance expires
check_status: "Current"No suspensions or restrictions
verified_atWhen Oho verified this status

Possible status values:

  • valid - Clearance is active and current
  • expired - Clearance has expired
  • suspended - Clearance has been suspended
  • cancelled - Clearance has been cancelled
  • not_found - No matching clearance found

What's Next?​

Congratulations! You've successfully submitted and received your first background check result.

Choose Your Path​

For Healthcare Organizations​

For Education Institutions​

For Childcare Providers​

For Aged Care Facilities​

Learn More About Check Types​

Deep Dive Into Integration​

Add People to Your Organization​

Common Issues & Solutions​

"Invalid token" Error​

Problem: Your API request returned 401 Unauthorized

Solution:

  • Verify you copied the entire JWT token (starts with eyJ...)
  • Check for extra spaces or newlines
  • Ensure you're using Bearer YOUR_JWT_TOKEN in the Authorization header
  • Confirm your email is verified
  • Token may have expired - get a new token using Step 2
  • Check your email/password are correct when getting the token

"Check not found" Error​

Problem: Status check returns 404 Not Found

Solution:

  • Wait a few seconds - checks typically complete in 2-10 seconds
  • Verify your correlation_id is correct
  • Check you're using the same JWT token for both submission and status check

"Invalid identifier" Error​

Problem: Check submission failed with validation error

Solution:

  • Verify the WWC card number format is correct for the state
  • Ensure all required fields are provided (first_name, surname, identifier)
  • Check birth_date format is YYYY-MM-DD
  • For NSW and SA, birth_date is mandatory

No Results After 30 Seconds​

Problem: Status check still shows "pending"

Solution:

  • Government registries occasionally have delays
  • Check again after 1-2 minutes
  • If still pending after 5 minutes, contact support with your correlation_id

Production Checklist​

Before going live with Oho in production:

  • Implement automatic JWT token refresh logic (tokens expire after 30 days)
  • Store credentials securely (environment variables, secrets manager)
  • Never commit email/password or JWT tokens to version control
  • Set up webhook endpoints for automated result delivery
  • Implement error handling and retry logic (especially for 401 token expiry)
  • Test with various check types relevant to your industry
  • Set up monitoring for webhook delivery failures
  • Configure expiry alerts for compliance tracking
  • Review security best practices
  • Implement the OhoClient class from the Authentication Guide for production use

Need Help?​

Time to First Success: ⏱️ Under 5 minutes Next Step: Choose your industry guide or explore all check types